From 2823547f2c70369da4438abe1fbf78a1d30bc8cf Mon Sep 17 00:00:00 2001 From: epriestley Date: Sat, 26 Apr 2014 22:30:19 -0700 Subject: [PATCH] Update contributor documentation Summary: It's fairly common for people to show up and be interested in finding easy stuff to work on. This stuff basically doesn't exist and probably never will: it doesn't make much sense to deliberately leave easy bugs broken just because someone might show up and want to fix a couple of easy bugs. Almost all of the work that's valuable to us requires a depth or bredth of context which can't be acquired in a few hours here and there, and probably always will. I think it also always //should//, in that as long as we continue refactoring and clearing technical debt aggressively and having solid static analysis support tools, we should never have a large backlog of human-intelligence codebase tasks. The closest we've ever come were probably `pht()` and `phutil_tag()`, which both have a lot of subtleties and we mostly automated `phutil_tag()` anyway. These tasks are also //incredibly boring// to write and review. So, accept this as a reality and realign the contributor documentation to try to deal with this case: - Set expectations about starter tasks not existing and throwing a couple of hours at the project writing code being a hard path. - Suggest non-code contributions which anyone can do. - Segue into code contributions with context and suggestions. Test Plan: Generated and read documentation. Reviewers: btrahan, chad Reviewed By: chad Subscribers: epriestley Differential Revision: https://secure.phabricator.com/D8872 --- src/docs/contributor/contrib_intro.diviner | 101 +++++++++++++++++---- 1 file changed, 84 insertions(+), 17 deletions(-) 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) -- 2.54.0