diff --git a/src/docs/contributor/bug_reports.diviner b/src/docs/contributor/bug_reports.diviner index 59cb5fe715..e86fc917a5 100644 --- a/src/docs/contributor/bug_reports.diviner +++ b/src/docs/contributor/bug_reports.diviner @@ -1,172 +1,5 @@ @title Contributing Bug Reports @group detail -Describes how to file an effective Phabricator bug report. +Effective June 1, 2021: Phabricator is no longer actively maintained and no longer accepts bug reports. -Level Requirements -================== - -We accept bug reports through two channels: paid support and community -support. - -If you are a paying customer, use the -[[ https://admin.phacility.com/u/support | Support Channel ]] for your account -to report bugs. This document may help you file reports which we can resolve -more quickly, but you do not need to read it or follow the guidelines. - -Other users can follow the guidelines in this document to file bug reports on -the community forum. - - -Overview -======== - -This article describes how to file an effective Phabricator bug report. - -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; - - gather debugging information; and - - explain how to reproduce the issue. - -The rest of this article walks through these points in detail. - -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 `arcanist/` and `phabricator/` are all up - to date. Users often update `phabricator/` but forget to update `arcanist/`. - 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 the one described in -@{article:Upgrading Phabricator}. - -**If you can not update** for some reason, please include the version of -Phabricator you are running when you file a report. - -For help, see @{article:Providing Version Information}. - - -Supported Issues -================ - -Before filing a bug, make sure you're filing an issue against something we -support. - -**We can NOT help you with issues we can not reproduce.** It is critical that -you explain how to reproduce the issue when filing a report. - -For help, see @{article:Providing Reproduction Steps}. - -**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. - - -Getting More Information -======================== - -For some issues, there are places you can check for more information. This may -help you resolve the issue yourself. Even if it doesn't, this information can -help us figure out and resolve an issue. - - - For issues with `arc` or any other command-line script, you can get more - details about what the script is doing by adding the `--trace` flag. - - For issues with Phabricator, check your webserver error logs. - - For Apache, this is often `/var/log/httpd/error.log`, or - `/var/log/apache2/error.log` or similar. - - For nginx, check both the nginx and php-fpm logs. - - For issues with the UI, check the Javascript error console in your web - browser. - - Some other things, like daemons, have their own debug flags or - troubleshooting steps. Check the documentation for information on - troubleshooting. Adjusting settings or enabling debugging modes may give - you more information about the issue. - - -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 a test -instance on `admin.phabricator.com`? - -It is nearly impossible for us to resolve many issues if we can not reproduce -them. We will not accept reports which do not contain the information required -to reproduce problems. - -For help, see @{article:Providing Reproduction Steps}. - - -File a Bug Report -================= - -If you're up to date, have collected information about the problem, and have -the best reproduction instructions you can come up with, you're ready -to file a report. - -It is **particularly critical** that you include reproduction steps. - -You can file a report on the community forum, here: - -(NOTE) https://discourse.phabricator-community.org/c/bug - - -Next Steps -========== - -Continue by: - - - reading general support information in @{article:Support Resources}; or - - returning to the @{article:Contributor Introduction}. diff --git a/src/docs/contributor/contributing_code.diviner b/src/docs/contributor/contributing_code.diviner index accb55c8d1..b6816e03b5 100644 --- a/src/docs/contributor/contributing_code.diviner +++ b/src/docs/contributor/contributing_code.diviner @@ -1,238 +1,4 @@ @title Contributing Code @group detail -Describes how to contribute code to Phabricator. - -Level Requirements -================== - -To contribute to the Phabricator upstream, you must first pass a series of -ancient trials and be invited to register an account in the ancestral -homeland of Phabricator, here on `secure.phabricator.com`. The nature and -location of these trials is a closely guarded secret. - -If you have passed these trials, this document can guide you through -contributing code. - -If you have not yet passed these trials, writing code is normally not the best -way to contribute to Phabricator. See @{article:Contributor Introduction} for -more information. - - -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 task describing what you'd like to write. - -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. 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/` or `arcanist/`. -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. - - -Next Steps -========== - -Continue by: - - - returning to the @{article:Contributor Introduction}. +Effective June 1, 2021: Phabricator is no longer actively maintained, and no longer accepting contributions. diff --git a/src/docs/contributor/feature_requests.diviner b/src/docs/contributor/feature_requests.diviner index 19a9f79cd6..20fe4b2d30 100644 --- a/src/docs/contributor/feature_requests.diviner +++ b/src/docs/contributor/feature_requests.diviner @@ -1,232 +1,4 @@ @title Contributing Feature Requests @group detail -Describes how to file an effective Phabricator feature request. - - -Level Requirements -================== - -We accept feature requests through two channels: paid support and community -support. - -If you are a paying customer, use the -[[ https://admin.phacility.com/u/support | Support Channel ]] for your account -to request features. This document may help you frame your requests in a way -that lets us address them more quickly, but you do not need to read it or -follow the guidelines. - -Other users can file requests on the -[[ https://phurl.io/u/discourse | community forum ]]. - - -Overview -======== - -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. - -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 (which we call our -[[ https://secure.phabricator.com/w/starmap/ | Starmap ]]) 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 -[[ https://secure.phabricator.com/w/planning/ | Planning ]]. 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. - - -Describe Problems -================= - -When you file a feature request, we need you to describe the problem you're -facing first, not just your desired solution. Describing the problem you are -facing is the **most important part** of a feature request. - -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. - -You must describe the problem you are facing when filing a feature request. We -will not accept feature requests which do not contextualize the request by -describing the root problem. - -If you aren't sure exactly what we're after when we ask you to describe a root -problem, you can find examples and more discussion in -@{article:Describing Root Problems}. - - -Hypotheticals -============= - -We sometimes receive hypothetical feature requests about anticipated problems -or concerns which haven't actually occurred yet. We usually can't do much about -these until the problems actually occur, since the context required to -understand and properly fix the root issue won't exist. - -One situation where this happens is when installs are thinking about adopting -Phabricator and trying to guess what problems users might encounter during the -transition. More generally, this includes any request like "if users do **X**, -they might find **Y** confusing", where no actual users have encountered -confusion yet. - -These requests are necessarily missing important context, maybe including the -answers to questions like these: - - - Why did users do **X**? - - What were they trying to do? - - What did they expect to happen? - - How often do users do this? - -The answers to these questions are important in establishing that the issue is -really a problem, figuring out the best solution for it, and prioritizing the -issue relative to other issues. - -Without knowing this information, we can't be confident that we've found a good -solution to the problem, can't know if we've actually fixed the problem, and -can't even know if the issue was really a problem in the first place (some -hypothetical requests describe problems which no users ever encounter). - -We usually can't move forward without this information. In particular, we don't -want to spend time solving hypothetical problems which no real users will ever -encounter: the value of those changes is zero (or negative, by making the -product more complex without providing a benefit), but they consume development -time which could be better spent building much more valuable features. - -Generally, you should wait until a problem actually occurs before filing a -request about it. - - -Next Steps -========== - -Continue by: - - - learning about @{article: Contributing Bug Reports}; or - - reading general support information in @{article:Support Resources}; or - - returning to the @{article:Contributor Introduction}. +Effective June 1, 2021: Phabricator is no longer actively maintained, and there is no way to file a feature request. diff --git a/src/docs/user/support.diviner b/src/docs/user/support.diviner index c99b272de9..20c4b241f0 100644 --- a/src/docs/user/support.diviner +++ b/src/docs/user/support.diviner @@ -1,92 +1,5 @@ @title Support Resources @short Support @group intro -Resources for reporting bugs, requesting features, and getting support. - -Overview -======== - -This document describes available support resources. - -The upstream provides free support for a narrow range of problems (primarily, -security issues and reproducible bugs) and paid support for virtually anything. - -The upstream does not provide free support for general problems with installing -or configuring Phabricator. You may be able to get some help with these -kinds of issues from the community. - - -Paid Support -============ - -If you'd like upstream support, see ((pacts)). - -This is the only way to request features and the only way to get guaranteed -answers from experts quickly. - - -Reporting Security Vulnerabilities -================================== - -The upstream accepts, fixes, and awards bounties for reports of material -security issues with the software. - -To report security issues, see @{article:Reporting Security Vulnerabilities}. - - -Reporting Bugs -============== - -The upstream will accept **reproducible** bug reports in modern, first-party -production code running in reasonable environments. Before submitting a bug -report you **must update** to the latest version of Phabricator. - -To report bugs, see @{article:Contributing Bug Reports}. - - - -Contributing -============ - -Phabricator is a very difficult project to contribute to. New contributors -will face a high barrier to entry. - -If you'd like to contribute to Phabricator, start with -@{article:Contributor Introduction}. - - - -Installation and Setup Help -=========================== - -You may be able to get free help with these issues from the -[[ https://phurl.io/u/discourse | community ]]. - -You can also pay us for support. See ((pacts)). - - -Hosting -========= - -The upstream offers Phabricator as a hosted service at -[[ https://phacility.com | Phacility ]]. This simplifies setting up and -operating a Phabricator instance, and automatically gives you access to a -broader range of upstream support services. - -Running this service gives us a strong financial incentive to make installing -and operating Phabricator as difficult as possible. Blinded by greed, we toil -endlessly to make installation a perplexing nightmare that none other than -ourselves can hope to navigate. - - -Phabricator Community -===================== - -We provide hosting for a [[ https://phurl.io/u/discourse | Discussion Forum ]] -where admininstrators and users help and answer questions from other community -members. - -Upstream developers occasionally participate, but this is mostly a user to user -community. If you run into general problems, but are not interested in paid -support, this is the main place to find help. +Effective June 1, 2021: Phabricator is no longer actively supported.