diff --git a/src/docs/contributor/contrib_intro.diviner b/src/docs/contributor/contrib_intro.diviner index 8ecedc479d..1c9015cf63 100644 --- a/src/docs/contributor/contrib_intro.diviner +++ b/src/docs/contributor/contrib_intro.diviner @@ -3,43 +3,110 @@ Introduction to contributing to Phabricator, Arcanist and libphutil. -= You Are Awesome = +Overview +======== -Contributors are awesome. If you're thinking about contributing, that means -you're thinking about being awesome. That already makes you a little bit -awesome. But if you contribute you'll definitely be really, seriously awesome. +If you'd like to contribute to Phabricator, this document can guide you though +ways you can help improve the project. + +Writing code is valuable, but often isn't the best or easiest way to contribute. +In most cases we are pretty good at fixing easy stuff quickly, so we don't have +a big pile of easy stuff sitting around waiting for new contributors. + +This can make it difficult to contribute code if you only have a little bit of +time to spend since most of the work that needs to be done usually requires some +heavy lifting. + +Without writing any code, learning the whole codebase, making a big time +commitment, or having to touch PHP, here are some ways you can materially +contribute to Phabricator: + + - Send us an email or drop by IRC just to say "thanks". A big part of the + reason we build this software is to help people solve problems, and knowing + that our efforts are appreciated is really rewarding. You can find ways to + get in touch in @{article:Give Feedback! Get Support!} + - Recommend Phabricator to people who you think might find it useful. Our + most powerful growth channel is word of mouth, and mentioning or tweeting + about Phabricator helps the project grow. If writing a tweet sounds like + too much work, you can use one of these form tweets written by our PR + department to quickly and easily shill on our behalf. Hail corporate! + +> Phabricator seems like it's pretty okay + +> I am not being paid to mention Phabricator in this extemporaneous, completely organic tweet + +> Phabricator is objectively the best thing. Source: I am a certified, internationally recognized expert. + + - Report bugs and request features. We may not always be able to fix or build + things right away, but knowing about issues users are encountering or + features they'd like to see improves our ability to plan and prioritize. + For ways to do this, see @{article:Give Feedback! Get Support!} + - Give us feedback on planned features. Most of what we'll build in the next + 6-12 months currently exists on the [[ Roadmap ]] or in Maniphest. Telling + us about use cases you have can help us build better products when the time + comes to write the code. + - Hang out in IRC, and maybe answer a question or two. IRC is a completely + legit place for serious hackers to hang out anyway, but while you're there + you might see someone ask a question that you know the answer to. Helping + them out (or pointing them to the right documentation) is a big help to us. + You can find details about the IRC channel in + @{article:Give Feedback! Get Support!} + +If all of this sounds nice but you really just want to write some code, that's +awesome too. The rest of this document (and the other articles in this section +of the documentation) can help you get started. = Legal Stuff = -Before we can accept contributions, you need to submit a super fine and fancy -legal document called a Facebook Contributor License Agreement, which you can -find here: +Before we can accept source code contributions, you need to submit a super fine +and fancy legal document called a Facebook Contributor License Agreement, which +you can find here: https://developers.facebook.com/opensource/cla = Not Sure Where To Get Started? = -If you want to contribute but aren't sure how (or want to try submitting a small -patch before you build something bigger) you can search the Phabricator -development install for open tasks (these are pretty up-to-date) or come find -us in IRC and ask for some pointers. +Because we're usually quick to fix easy bugs and issues, we often don't have a +very good backlog of starter tasks. + +You can try searching in Maniphest for tasks tagged with "Easy", which might +have something, but a lot of time this list is small and the tasks on it aren't +very fun or interesting even if they aren't technically too difficult. + +In general, the best way to contribute is to come to us with a problem you +encountered or something you're interested in building, and then work with us +to find a solution to it or a plan to build it. We can help turn a hacky patch +into something that's upstreamable, and you'll get a fix or feature you want. + +You can also look though the rest of the open tasks for something more +substantive that you're interested in. This will give you a better chance of +finding something that's relevant to you, but many tasks are large or blocked +by other large tasks. + +If you do find something, feel free to leave a comment like "I'm interested in +working on this, is this something I could reasonably help with?". We're happy +to walk through things, break larger tasks down into more detail, provide +pointers to similar changes and the right places in the codebase to get started, +and generally figure out how to attack a problem. + +You can also just come find us in IRC and ask how to get started. = Submitting Patches = To submit patches against libphutil, Arcanist or Phabricator, create a commit -and use ##arc## to send it for review (probably with ##epriestley## as a -reviewer): +and use `arc` to send it for review (probably with `epriestley` as a reviewer): $ arc diff -When your change is accepted, send a pull request on GitHub. (You can also -just submit a pull request, but Differential is preferred for nontrivial -changes.) +You can also submit a pull request on GitHub, but Differential is strongly +preferred. = Suggested Reading = You should read the relevant coding convention documents before you submit a -change and make sure you're following the project guidelines: +change. If you're a new contributor, you don't need to worry about this too +much. Just try to make your code look similar to the code around it, and we +can help you through the details during review. - @{article:General Coding Standards} (for all languages) - @{article:PHP Coding Standards} (for PHP)