Remove documentation for support, feature requests, contributing code, and filing bug reports

Summary: Ref T13654. Test Plan: Read documents. Maniphest Tasks: T13654 Differential Revision: https://secure.phabricator.com/D21665
2024-11-25 16:22:43 +01:00 · 2021-05-29 14:08:35 -07:00 · 2021-05-29 14:08:35 -07:00 · ad05ee00c0
commit ad05ee00c0
parent 9ceb664535
4 changed files with 4 additions and 720 deletions
--- 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}.
--- 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.
+Effective June 1, 2021: Phabricator is no longer actively maintained, and no longer accepting contributions.
 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}.
--- 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.
+Effective June 1, 2021: Phabricator is no longer actively maintained, and there is no way to file a 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}.
--- a/src/docs/user/support.diviner
+++ b/src/docs/user/support.diviner
@ -2,91 +2,4 @@
@short Support
@group intro
-Resources for reporting bugs, requesting features, and getting support.
+Effective June 1, 2021: Phabricator is no longer actively supported.
 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.