diff --git a/src/docs/book/contributor.book b/src/docs/book/contributor.book --- a/src/docs/book/contributor.book +++ b/src/docs/book/contributor.book @@ -23,6 +23,9 @@ "contrib" : { "name" : "Contributor Overview" }, + "detail": { + "name" : "Contributing in Detail" + }, "standards" : { "name" : "Coding Standards" }, diff --git a/src/docs/contributor/bug_reports.diviner b/src/docs/contributor/bug_reports.diviner new file mode 100644 --- /dev/null +++ b/src/docs/contributor/bug_reports.diviner @@ -0,0 +1,159 @@ +@title Contributing Bug Reports +@group detail + +Describes how to file an effective Phabricator bug report. + +Overview +======== + +Found a bug with Phabricator? Let us know! This article describes how to file +an effective bug report so we can get your issue fixed or help you work around +it. + +The most important things to do are: + + - check the list of common fixes below; + - make sure Phabricator is up to date; + - make sure we support your setup; + - explain how to reproduce the issue; and + - create a task in + [[ http://secure.phabricator.com/maniphest/task/create/ | Maniphest ]]. + +The rest of this article walks through these points in detail. + +If you have a feature request (not a bug report), see +@{article:Contributing Feature Requests} for a more tailored guide. + +For general information on contributing to Phabricator, see +@{article:Contributor Introduction}. + +Common Fixes +============ + +Before you file a report, here are some common solutions to problems: + + - **Update Phabricator**: We receive a lot of bug reports about issues we have + already fixed in HEAD. Updating often resolves issues. It is common for + issues to be fixed in less than 24 hours, so even if you've updated recently + you should update again. If you aren't sure how to update, see the next + section. + - **Update Libraries**: Make sure `libphutil/`, `arcanist/` and + `phabricator/` are all up to date. Users often update `phabricator/` but + forget to update `arcanist/` or `libphutil/`. When you update, make sure you + update all three libraries. + - **Restart Apache or PHP-FPM**: Phabricator uses caches which don't get + reset until you restart Apache or PHP-FPM. After updating, make sure you + restart. + + +Update Phabricator +================== + +Before filing a bug, make sure you are up to date. We receive many bug reports +for issues we have already fixed, and even if we haven't fixed an issue we'll +be able to resolve it more easily if you file a report based on HEAD. (For +example, an old stack trace may not have the right line numbers, which will +make it more difficult for us to figure out what's going wrong.) + +To update Phabricator, use a script like this one: + + http://www.phabricator.com/rsrc/install/update_phabricator.sh + +This script will require some adjustments depending on how your setup is +configured, which webserver you are using, etc. + +**If you can not update** for some reason, please include the version of +Phabricator you are running in your report. The version is just the Git hash +of your local HEAD. You can find the version by running `git show` in +`phabricator/` and copy/pasting the first line of output, or by browsing to +{nav Config > All Settings} in the web UI and copy/pasting the information +at the top. + + +Supported Issues +================ + +Before filing a bug, make sure you're filing an issue against something we +support. + +**We do NOT support prototype applications.** If you're running into an issue +with a prototype application, you're on your own. For more information about +prototype applications, see @{article:User Guide: Prototype Applications}. + +**We do NOT support third-party packages or instructions.** If you installed +Phabricator (or configured some aspect of it) using a third-party package or by +following a third-party guide (like a blog post), we can not help you. +Phabricator changes quickly and third-party information is unreliable and often +falls out of date. Contact the maintainer of the package or guide you used, +or reinstall following the upstream instructions. + +**We do NOT support custom code development or third-party libraries.** If +you're writing an extension, you're on your own. We provide some documentation, +but can not help you with extension or library development. If you downloaded a +library from somewhere, contact the library maintainer. + +**We do NOT support bizarre environments.** If your issue is specific to an +unusual installation environment, we generally will not help you find a +workaround. Install Phabricator in a normal environment instead. Examples of +unusual environments are shared hosts, nontraditional hosts (gaming consoles, +storage appliances), and hosts with unusually tight resource constraints. The +vast majority of users run Phabricator in normal environments (modern computers +with root access) and these are the only environments we support. + +Otherwise, if you're having an issue with a supported first-party application +and followed the upstream install instructions on a normal computer, we're happy +to try to help. + + +Reproducibility +=============== + +The most important part of your report content is instructions on how to +reproduce the issue. What did you do? If you do it again, does it still break? +Does it depend on a specific browser? Can you reproduce the issue on +`secure.phabricator.com`? Feel free to try to reproduce issues on the upstream +install (which is kept near HEAD), within reason -- it's okay to make a few test +objects if you're having trouble narrowing something down or want to check if +updating might fix an issue. + +It is nearly impossible for us to resolve many issues if we can not reproduce +them. For more information, see @{article: Give Feedback! Get Support!}. + + +Create a Task in Maniphest +========================== + +If you're up to date, supported, and have the best reproduction instructions +you can come up with, you're ready to file an issue. + +We'll look at any issue report we can find (we monitor IRC, email, GitHub, +StackOverflow, Quora, Facebook and Twitter), but the upstream Maniphest is +the authoritative bug tracker and the best place to file: + + https://secure.phabricator.com/maniphest/task/create/ + +If you don't want to file there (or, for example, your bug relates to being +unable to log in or unable to file an issue in Maniphest) you can file on any of +the other channels, but we can address reports much more effectively if they're +filed against the upstream than if they're filed somewhere else. + +| Effectiveness | Filing Method | +|---|---| +| Best | Upstream Maniphest | +| Okay | GitHub | +| Ehhh | Quora, StackOverflow, Facebook, email, etc. | +| What | Passive-aggressive tweet | + +If you have a quick question or want to discuss something before filing an +issue, IRC is a great way to get a sanity check first. You can find information +about these channels in @{article: Give Feedback! Get Support!}. + +Next Steps +========== + +Continue by: + + - learning about @{article: Contributing Feature Requests}; or + - reading general support information in + @{article: Give Feedback! Get Support!}; or + - returning to the @{article:Contributor Introduction}. diff --git a/src/docs/contributor/contrib_intro.diviner b/src/docs/contributor/contrib_intro.diviner --- a/src/docs/contributor/contrib_intro.diviner +++ b/src/docs/contributor/contrib_intro.diviner @@ -41,6 +41,9 @@ 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!} + - For details on reporting bugs, see @{article:Contributing Bug Reports}. + - For details on requesting features, see @{article:Contributing Feature + Requests}. - 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 @@ -53,70 +56,15 @@ @{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. +awesome too. To get started with contributing code, see +@{article:Contributing Code}. -= Legal Stuff = +Next Steps +========== -Before we can accept source code contributions, you need to submit a -[[ https://secure.phabricator.com/L28 | Contributor License Agreement ]]. Your -changes can not be accepted until you sign the agreement. +Continue by: -If you haven't signed it by the time you send changes for review, you'll be -reminded to sign it at that time. - -If you're submitting work on behalf of a company (like your employer), the -company can sign the [[ https://secure.phabricator.com/L30 | Corporate -Contributor License Agreement ]] instead. - -Both agreements are substantially similar to the Apache Foundation's CLAs. They -protect Phacility and users of Phabricator by making sure we have permission to -distribute your changes under an open source license. - -= Not Sure Where To Get Started? = - -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): - - $ arc diff - -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. 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) - - @{article:Javascript Coding Standards} (for Javascript) + - learning about bug reports in @{article:Contributing Bug Reports}; + - learning about feature requests in @{article:Contributing Feature Requests}; + - learning about code contributions in @{article:Contributing Code}; or + - getting in touch with @{article:Give Feedback! Get Support!} diff --git a/src/docs/contributor/contributing_code.diviner b/src/docs/contributor/contributing_code.diviner new file mode 100644 --- /dev/null +++ b/src/docs/contributor/contributing_code.diviner @@ -0,0 +1,256 @@ +@title Contributing Code +@group detail + +Describes how to contribute code to Phabricator. + +Overview +======== + +If you're planning to send a patch to Phabricator, this guide can help you +through the process. The most important parts of contributing code to +Phabricator are: + + - File a task with a bug report or feature request //before// you write code. + - We rarely accept patches which we haven't discussed first. + - We do not accept patches against prototype applications. + - You must sign the CLA. + - We do not accept GitHub pull requests. + - Some alternative approaches are available if your change isn't something + we want to bring upstream. + +The rest of this article describes these points in more detail, and then +provides guidance on writing and submitting patches. + +If you just want to contribute some code but don't have a specific bug or +feature in mind, see the bottom of this document for tips on finding ways to get +started. + +For general information on contributing to Phabricator, see +@{article:Contributor Introduction}. + + +Coordinate First +================ + +Before sending code, you should file a bug report or feature request describing +what you'd like to write. For details on how to do this, see these articles: + + - @{article:Contributing Bug Reports} + - @{article:Contributing Feature Requests} + +When you file a task, mention that you'd like to write the code to fix it. We +can help contextualize your request or bug and guide you through writing an +upstreamable patch, provided it's something that's upstreamable. If it isn't +upstreamable, we can let you know what the issues are and help find another +plan of attack. + +You don't have to file first (for example, if you spot a misspelling it's +normally fine to just send a diff), but for anything even moderately complex +you're strongly encouraged to file first and coordinate with the upstream. + + +Rejecting Patches +================= + +If you send us a patch without coordinating it with us first, it will probably +be immediately rejected, or sit in limbo for a long time and eventually be +rejected. The reasons we do this vary from patch to patch, but some of the most +common reasons are: + +**Unjustifiable Costs**: We support code in the upstream forever. Support is +enormously expensive and takes up a huge amount of our time. The cost to support +a change over its lifetime is often 10x or 100x or 1000x greater than the cost +to write the first version of it. Many uncoordinated patches we receive are +"white elephants", which would cost much more to maintain than the value they +provide. + +As an author, it may look like you're giving us free work and we're rejecting it +as too expensive, but this viewpoint doesn't align with the reality of a large +project which is actively supported by a small, experienced team. Writing code +is cheap; maintaining it is expensive. + +By coordinating with us first, you can make sure the patch is something we +consider valuable enough to put long-term support resources behind, and that +you're building it in a way that we're comfortable taking over. + +**Not a Good Fit**: Many patches aren't good fits for the upstream: they +implement features we simply don't want. You can find more information in +@{article:Contributing Feature Requests}. Coordinating with us first helps +make sure we're on the same page and interested in a feature. + +The most common type of patch along these lines is a patch which adds new +configuration options. We consider additional configuration options to have +an exceptionally high lifetime support cost and are very unlikely to accept +them. Coordinate with us first. + +**Not a Priority**: If you send us a patch against something which isn't a +priority, we probably won't have time to look at it. We don't give special +treatment to low-priority issues just because there's code written: we'd still +be spending time on something lower-priority when we could be spending it on +something higher-priority instead. + +If you coordinate with us first, you can make sure your patch is in an area +of the codebase that we can prioritize. + +**Overly Ambitious Patches**: Sometimes we'll get huge patches from new +contributors. These can have a lot of fundamental problems and require a huge +amount of our time to review and correct. If you're interested in contributing, +you'll have more success if you start small and learn as you go. + +We can help you break a large change into smaller pieces and learn how the +codebase works as you proceed through the implementation, but only if you +coordinate with us first. + +**Generality**: We often receive several feature requests which ask for similar +features, and can come up with a general approach which covers all of the use +cases. If you send us a patch for //your use case only//, the approach may be +too specific. When a cleaner and more general approach is available, we usually +prefer to pursue it. + +By coordinating with us first, we can make you aware of similar use cases and +opportunities to generalize an approach. These changes are often small, but can +have a big impact on how useful a piece of code is. + +**Infrastructure and Sequencing**: Sometimes patches are written against a piece +of infrastructure with major planned changes. We don't want to accept these +because they'll make the infrastructure changes more difficult to implement. + +Coordinate with us first to make sure a change doesn't need to wait on other +pieces of infrastructure. We can help you identify technical blockers and +possibly guide you through resolving them if you're interested. + + +No Prototype Changes +==================== + +With rare exceptions, we do not accept patches for prototype applications for +the same reasons that we don't accept feature requests or bug reports. To learn +more about prototype applications, see +@{article:User Guide: Prototype Applications}. + + +You Must Sign the CLA +===================== + +Before we can accept source code contributions, you need to submit a +[[ https://secure.phabricator.com/L28 | Contributor License Agreement ]]. Your +changes can not be accepted until you sign the agreement. + +If you haven't signed it by the time you send changes for review, you'll be +reminded to sign it at that time. + +If you're submitting work on behalf of a company (like your employer), the +company can sign the [[ https://secure.phabricator.com/L30 | Corporate +Contributor License Agreement ]] instead. + +Both agreements are substantially similar to the Apache Foundation's CLAs. They +protect Phacility and users of Phabricator by making sure we have permission to +distribute your changes under an open source license. + + +No Pull Requests +================ + +We do not accept pull requests on GitHub: + + - We can not monitor who has signed CLAs on GitHub. You must sign the CLA + to contribute, and we can't tell if you've signed it or not when you send + us a pull request. + - Pull requests do not get lint and unit tests run, so issues which are + normally caught statically can slip by. + - Phabricator is code review software, and developed using its own workflows. + Pull requests bypass some of these workflows (for example, they will not + trigger Herald rules to notify interested parties). + - GitHub is not the authoritative master repository and we maintain a linear + history, so merging pull requests is cumbersome on our end. + - If you're comfortable enough with Phabricator to contribute to it, you + should also be comfortable using it to submit changes. + +Instead of sending a pull request, use `arc diff` to create a revision on the +upstream install. Your change will go through the normal Phabricator review +process. + +(GitHub does not allow repositories to disable pull requests, which is why +it's technically possible to submit them.) + + +Alternatives +============ + +If you've written code but we're not accepting it into the upstream, some +alternative approaches include: + +**Maintain a local fork.** This will require some ongoing effort to port your +changes forward when you update, but is often very reasonable for simple +changes. + +**Develop as an application.** Many parts of Phabricator's infrastructure are +modular, and modularity is increasing over time. A lot of changes can be built +as external modules or applications without forking Phabricator itself. There +isn't much documentation or support for this right now, but you can look at +how other applications are implemented, and at other third-party code that +extends Phabricator. + +**Rise to prominence.** We're more willing to accept borderline changes from +community members who are active, make multiple contributions, or have a history +with the project. This is not carte blanche, but distinguishing yourself can +make us feel more comfortable about supporting a change which is slightly +outside of our comfort zone. + + +Writing and Submitting Patches +================== + +To actually submit a patch, run `arc diff` in `phabricator/`, `arcanist/`, or +`libphutil/`. When executed in these directories, `arc` should automatically +talk to the upstream install. You can add `epriestley` as a reviewer. + +You should read the relevant coding convention documents before you submit a +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) + - @{article:Javascript Coding Standards} (for Javascript) + +In general, if you're coordinating with us first, we can usually provide +guidance on how to implement things. The other articles in this section also +provide information on how to work in the Phabricator codebase. + +Not Sure Where To Get Started? +============================== + +If you don't have a specific bug or feature in mind and just want to write +some code, you can try to find something simple to get started with. + +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. + + +Next Steps +========== + +Continue by: + + - returning to the @{article:Contributor Introduction}. diff --git a/src/docs/contributor/feature_requests.diviner b/src/docs/contributor/feature_requests.diviner new file mode 100644 --- /dev/null +++ b/src/docs/contributor/feature_requests.diviner @@ -0,0 +1,189 @@ +@title Contributing Feature Requests +@group detail + +Describes how to file an effective Phabricator feature request. + +Overview +======== + +Have a feature you'd like to see in Phabricator? This article describes how +to file an effective feature request. + +The most important things to do are: + + - understand the upstream; + - make sure your feature makes sense in the project; + - align your expectations around timelines and priorities; + - describe your problem, not your solution; and + - file a task in + [[ http://secure.phabricator.com/maniphest/task/create/ | Maniphest ]]. + +The rest of this article walks through these points in detail. + +If you have a bug report (not a feature request), see +@{article:Contributing Bug Reports} for a more tailored guide. + +For general information on contributing to Phabricator, see +@{article:Contributor Introduction}. + + +Understanding the Upstream +========================== + +Before filing a feature request, it may be useful to understand how the +upstream operates. + +The Phabricator upstream is [[ https://www.phacility.com | Phacility, Inc ]]. +We maintain total control over the project and roadmap. There is no democratic +process, voting, or community-driven decision making. This model is better +at some things and worse at others than a more community-focused model would +be, but it is the model we operate under. + +We have a cohesive vision for the project in the long term, and a general +roadmap that extends for years into the future. While the specifics of how +we get there are flexible, many major milestones are well-established. + +Although we set project direction, the community is also a critical part of +Phabricator. We aren't all-knowing, and we rely on feedback to help us identify +issues, guide product direction, prioritize changes, and suggest features. + +Feature requests are an important part of this, but we ultimately build only +features which make sense as part of the long term plan. + +Since it's hard to absorb a detailed understanding of that vision, //describing +a problem// is often more effective than //requesting a feature//. We have the +context to develop solutions which fit into our plans, address similar use +cases, make sense with the available infrastructure, and work within the +boundaries of our product vision. For more details on this, see below. + + +Target Audiences +================ + +Some feature requests support very unusual use cases. Although we are broadly +inclusive of many different kinds of users and use cases, we are not trying +to make the software all things to all users. Use cases which are far afield +from the things the majority of users do with Phabricator often face substantial +barriers. + +Phabricator is primarily targeted at software projects and organizations with +a heavy software focus. We are most likely to design, build, and prioritize +features which serve these organizations and projects. + +Phabricator is primarily targeted at software professionals and other +professionals with adjacent responsibilities (like project management and +operations). Particularly, we assume users are proficient computer users and +familiar with software development concepts. We are most likely to design, build +and prioritize features which serve these users. + +Phabricator is primarily targeted at professionals working in teams on full-time +projects. Particularly, we assume most users will use the software regularly and +are often willing to spend a little more time up front to get a more efficient +workflow in the long run. We are most likely to design, build and prioritize +features which serve these use cases. + +Phabricator is not limited to these kinds of organizations, users and use cases, +but features which are aimed at a different group of users (like students, +casual projects, or inexperienced computer users) may be harder to get +upstreamed. Features aimed at very different groups of users (like wedding +planners, book clubs, or dogs) will be much harder to get upstreamed. + +In many cases, a feature makes something better for all users. For example, +suppose we fixed an issue where colorblind users had difficulty doing something. +Dogs would benefit the most, but colorblind human users would also benefit, and +no one would be worse off. If the benefit for core users is very small these +kinds of features may be hard to prioritize, but there is no exceptional barrier +to getting them upstreamed. + +In other cases, a feature makes something better for some users and worse for +other users. These kinds of features face a high barrier if they make the +software better at planning weddings and worse at reviewing code. + + +Setting Expectations +==================== + +We have a lot of users and a small team. Even if your feature is something we're +interested in and a good fit for where we want the product to go, it may take +us a long time to get around to building it. + +We work full time on Phabricator, and our long-term roadmap has many years worth +of work. Your feature request is competing against thousands of other requests +for priority. + +In general, we try to prioritize work that will have the greatest impact on the +most users. Many feature requests are perfectly reasonable requests, but have +very little impact, impact only a few users, and/or are complex to develop and +support relative to their impact. It can take us a long time to get to these. + +Even if your feature request is simple and has substantial impact for a large +number of users, the size of the request queue means that it is mathematically +unlikely to be near the top. + +You can find some information about how we prioritize in T4778. In particular, +we reprioritize frequently and can not accurately predict when we'll build a +feature which isn't very near to top of the queue. + +As a whole, this means that the overwhelming majority of feature requests will +sit in queue for a long time without any updates, and that we won't be able to +give you any updates or predictions about timelines. One day, out of nowhere, +your feature will materialize. That day may be a decade from now. You should +have realistic expectations about this when filing a feature request. + +If you want a concrete timeline, you can build the feature yourself. See +@{article:Contributing Code} for details and alternatives to working with the +upstream. + + +Describe Problems +================= + +When you file a feature request, it is really helpful to describe the problem +you're facing first, not just your desired solution. + +Often, your problem may have a lot in common with other similar problems. If we +understand your use case we can compare it to other use cases and sometimes find +a more powerful or more general solution which solves several problems at once. + +At other times, we'll have a planned solution to the problem that might be +different from your desired solution but accomplish the same goal. Understanding +the root issue can let us merge and contextualize things. + +Sometimes there's already a way to solve your problem that might just not be +obvious. + +Finally, your proposed solution may not be compatible with the direction we +want to take the product, but we may be able to come up with another solution +which has approximately the same effect and does fit into the product direction. + +If you only describe the solution and not the problem, we can't generalize, +contextualize, merge, reframe, or offer alternative solutions or workarounds. + + +Create a Task in Maniphest +========================== + +If you think your feature might be a good fit for the upstream, have reasonable +expectations about it, and have a good description of the problem you're trying +to solve, you're ready to file a feature request: + + https://secure.phabricator.com/maniphest/task/create/ + +You can file feature requests in places other than Maniphest (like GitHub), but +we can address them far more effectively if you file them in the upstream. +Feature requests filed elsewhere will generally be moved to the upstream. + +If you have a quick question or want to discuss something before filing a +request, IRC is a great way to get a quick answer. You can find information +about IRC and other support channels in @{article: Give Feedback! Get Support!}. + + +Next Steps +========== + +Continue by: + + - learning about @{article: Contributing Bug Reports}; or + - reading general support information in + @{article: Give Feedback! Get Support!}; or + - returning to the @{article:Contributor Introduction}.