src/docs/contributor/bug_reports.diviner

   1 @title Contributing Bug Reports
   2 @group detail
   3
   4 Describes how to file an effective Phabricator bug report.
   5
   6 Level Requirements
   7 ==================
   8
   9 We accept bug reports through two channels: paid support and community
  10 support.
  11
  12 If you are a paying customer, use the
  13 [[ https://admin.phacility.com/u/support | Support Channel ]] for your account
  14 to report bugs. This document may help you file reports which we can resolve
  15 more quickly, but you do not need to read it or follow the guidelines.
  16
  17 Other users can follow the guidelines in this document to file bug reports on
  18 the community forum.
  19
  20
  21 Overview
  22 ========
  23
  24 This article describes how to file an effective Phabricator bug report.
  25
  26 The most important things to do are:
  27
  28   - check the list of common fixes below;
  29   - make sure Phabricator is up to date;
  30   - make sure we support your setup;
  31   - gather debugging information; and
  32   - explain how to reproduce the issue.
  33
  34 The rest of this article walks through these points in detail.
  35
  36 For general information on contributing to Phabricator, see
  37 @{article:Contributor Introduction}.
  38
  39
  40 Common Fixes
  41 ============
  42
  43 Before you file a report, here are some common solutions to problems:
  44
  45   - **Update Phabricator**: We receive a lot of bug reports about issues we have
  46     already fixed in HEAD. Updating often resolves issues. It is common for
  47     issues to be fixed in less than 24 hours, so even if you've updated recently
  48     you should update again. If you aren't sure how to update, see the next
  49     section.
  50   - **Update Libraries**: Make sure `libphutil/`, `arcanist/` and
  51     `phabricator/` are all up to date. Users often update `phabricator/` but
  52     forget to update `arcanist/` or `libphutil/`. When you update, make sure you
  53     update all three libraries.
  54   - **Restart Apache or PHP-FPM**: Phabricator uses caches which don't get
  55     reset until you restart Apache or PHP-FPM. After updating, make sure you
  56     restart.
  57
  58
  59 Update Phabricator
  60 ==================
  61
  62 Before filing a bug, make sure you are up to date. We receive many bug reports
  63 for issues we have already fixed, and even if we haven't fixed an issue we'll
  64 be able to resolve it more easily if you file a report based on HEAD. (For
  65 example, an old stack trace may not have the right line numbers, which will
  66 make it more difficult for us to figure out what's going wrong.)
  67
  68 To update Phabricator, use a script like the one described in
  69 @{article:Upgrading Phabricator}.
  70
  71 **If you can not update** for some reason, please include the version of
  72 Phabricator you are running when you file a report.
  73
  74 For help, see @{article:Providing Version Information}.
  75
  76
  77 Supported Issues
  78 ================
  79
  80 Before filing a bug, make sure you're filing an issue against something we
  81 support.
  82
  83 **We can NOT help you with issues we can not reproduce.** It is critical that
  84 you explain how to reproduce the issue when filing a report.
  85
  86 For help, see @{article:Providing Reproduction Steps}.
  87
  88 **We do NOT support prototype applications.** If you're running into an issue
  89 with a prototype application, you're on your own. For more information about
  90 prototype applications, see @{article:User Guide: Prototype Applications}.
  91
  92 **We do NOT support third-party packages or instructions.** If you installed
  93 Phabricator (or configured some aspect of it) using a third-party package or by
  94 following a third-party guide (like a blog post), we can not help you.
  95 Phabricator changes quickly and third-party information is unreliable and often
  96 falls out of date. Contact the maintainer of the package or guide you used,
  97 or reinstall following the upstream instructions.
  98
  99 **We do NOT support custom code development or third-party libraries.** If
 100 you're writing an extension, you're on your own. We provide some documentation,
 101 but can not help you with extension or library development. If you downloaded a
 102 library from somewhere, contact the library maintainer.
 103
 104 **We do NOT support bizarre environments.** If your issue is specific to an
 105 unusual installation environment, we generally will not help you find a
 106 workaround. Install Phabricator in a normal environment instead. Examples of
 107 unusual environments are shared hosts, nontraditional hosts (gaming consoles,
 108 storage appliances), and hosts with unusually tight resource constraints. The
 109 vast majority of users run Phabricator in normal environments (modern computers
 110 with root access) and these are the only environments we support.
 111
 112 Otherwise, if you're having an issue with a supported first-party application
 113 and followed the upstream install instructions on a normal computer, we're happy
 114 to try to help.
 115
 116
 117 Getting More Information
 118 ========================
 119
 120 For some issues, there are places you can check for more information. This may
 121 help you resolve the issue yourself. Even if it doesn't, this information can
 122 help us figure out and resolve an issue.
 123
 124   - For issues with `arc` or any other command-line script, you can get more
 125     details about what the script is doing by adding the `--trace` flag.
 126   - For issues with Phabricator, check your webserver error logs.
 127     - For Apache, this is often `/var/log/httpd/error.log`, or
 128       `/var/log/apache2/error.log` or similar.
 129     - For nginx, check both the nginx and php-fpm logs.
 130   - For issues with the UI, check the Javascript error console in your web
 131     browser.
 132   - Some other things, like daemons, have their own debug flags or
 133     troubleshooting steps. Check the documentation for information on
 134     troubleshooting. Adjusting settings or enabling debugging modes may give
 135     you more information about the issue.
 136
 137
 138 Reproducibility
 139 ===============
 140
 141 The most important part of your report content is instructions on how to
 142 reproduce the issue. What did you do? If you do it again, does it still break?
 143 Does it depend on a specific browser? Can you reproduce the issue on a test
 144 instance on `admin.phabricator.com`?
 145
 146 It is nearly impossible for us to resolve many issues if we can not reproduce
 147 them. We will not accept reports which do not contain the information required
 148 to reproduce problems.
 149
 150 For help, see @{article:Providing Reproduction Steps}.
 151
 152
 153 File a Bug Report
 154 =================
 155
 156 If you're up to date, have collected information about the problem, and have
 157 the best reproduction instructions you can come up with, you're ready
 158 to file a report.
 159
 160 It is **particularly critical** that you include reproduction steps.
 161
 162 You can file a report on the community forum, here:
 163
 164 (NOTE) https://discourse.phabricator-community.org/c/bug
 165
 166
 167 Next Steps
 168 ==========
 169
 170 Continue by:
 171
 172   - reading general support information in @{article:Support Resources}; or
 173   - returning to the @{article:Contributor Introduction}.