[Summary view] [Print] [Text view]

   1  @title Contributing Bug Reports
   2  @group detail
   3  
   4  Describes how to file an effective Phabricator bug report.
   5  
   6  Overview
   7  ========
   8  
   9  Found a bug with Phabricator? Let us know! This article describes how to file
  10  an effective bug report so we can get your issue fixed or help you work around
  11  it.
  12  
  13  The most important things to do are:
  14  
  15    - check the list of common fixes below;
  16    - make sure Phabricator is up to date;
  17    - make sure we support your setup;
  18    - gather debugging information;
  19    - explain how to reproduce the issue; and
  20    - create a task in
  21      [[ http://secure.phabricator.com/maniphest/task/create/ | Maniphest ]].
  22  
  23  The rest of this article walks through these points in detail.
  24  
  25  If you have a feature request (not a bug report), see
  26  @{article:Contributing Feature Requests} for a more tailored guide.
  27  
  28  For general information on contributing to Phabricator, see
  29  @{article:Contributor Introduction}.
  30  
  31  Common Fixes
  32  ============
  33  
  34  Before you file a report, here are some common solutions to problems:
  35  
  36    - **Update Phabricator**: We receive a lot of bug reports about issues we have
  37      already fixed in HEAD. Updating often resolves issues. It is common for
  38      issues to be fixed in less than 24 hours, so even if you've updated recently
  39      you should update again. If you aren't sure how to update, see the next
  40      section.
  41    - **Update Libraries**: Make sure `libphutil/`, `arcanist/` and
  42      `phabricator/` are all up to date. Users often update `phabricator/` but
  43      forget to update `arcanist/` or `libphutil/`. When you update, make sure you
  44      update all three libraries.
  45    - **Restart Apache or PHP-FPM**: Phabricator uses caches which don't get
  46      reset until you restart Apache or PHP-FPM. After updating, make sure you
  47      restart.
  48  
  49  
  50  Update Phabricator
  51  ==================
  52  
  53  Before filing a bug, make sure you are up to date. We receive many bug reports
  54  for issues we have already fixed, and even if we haven't fixed an issue we'll
  55  be able to resolve it more easily if you file a report based on HEAD. (For
  56  example, an old stack trace may not have the right line numbers, which will
  57  make it more difficult for us to figure out what's going wrong.)
  58  
  59  To update Phabricator, use a script like this one:
  60  
  61  http://www.phabricator.com/rsrc/install/update_phabricator.sh
  62  
  63  This script will require some adjustments depending on how your setup is
  64  configured, which webserver you are using, etc.
  65  
  66  **If you can not update** for some reason, please include the version of
  67  Phabricator you are running in your report. The version is just the Git hash
  68  of your local HEAD. You can find the version by running `git show` in
  69  `phabricator/` and copy/pasting the first line of output, or by browsing to
  70  {nav Config > All Settings} in the web UI and copy/pasting the information
  71  at the top.
  72  
  73  
  74  Supported Issues
  75  ================
  76  
  77  Before filing a bug, make sure you're filing an issue against something we
  78  support.
  79  
  80  **We do NOT support prototype applications.** If you're running into an issue
  81  with a prototype application, you're on your own. For more information about
  82  prototype applications, see @{article:User Guide: Prototype Applications}.
  83  
  84  **We do NOT support third-party packages or instructions.** If you installed
  85  Phabricator (or configured some aspect of it) using a third-party package or by
  86  following a third-party guide (like a blog post), we can not help you.
  87  Phabricator changes quickly and third-party information is unreliable and often
  88  falls out of date. Contact the maintainer of the package or guide you used,
  89  or reinstall following the upstream instructions.
  90  
  91  **We do NOT support custom code development or third-party libraries.** If
  92  you're writing an extension, you're on your own. We provide some documentation,
  93  but can not help you with extension or library development. If you downloaded a
  94  library from somewhere, contact the library maintainer.
  95  
  96  **We do NOT support bizarre environments.** If your issue is specific to an
  97  unusual installation environment, we generally will not help you find a
  98  workaround. Install Phabricator in a normal environment instead. Examples of
  99  unusual environments are shared hosts, nontraditional hosts (gaming consoles,
 100  storage appliances), and hosts with unusually tight resource constraints. The
 101  vast majority of users run Phabricator in normal environments (modern computers
 102  with root access) and these are the only environments we support.
 103  
 104  Otherwise, if you're having an issue with a supported first-party application
 105  and followed the upstream install instructions on a normal computer, we're happy
 106  to try to help.
 107  
 108  Getting More Information
 109  ========================
 110  
 111  For some issues, there are places you can check for more information. This may
 112  help you resolve the issue yourself. Even if it doesn't, this information can
 113  help us figure out and resolve an issue.
 114  
 115    - For issues with `arc` or any other command-line script, you can get more
 116      details about what the script is doing by adding the `--trace` flag.
 117    - For issues with Phabricator, check your webserver error logs.
 118      - For Apache, this is often `/var/log/httpd/error.log`, or
 119        `/var/log/apache2/error.log` or similar.
 120      - For nginx, check both the nginx and php-fpm logs.
 121    - For issues with the UI, check the Javascript error console in your web
 122      browser.
 123    - Some other things, like daemons, have their own debug flags or
 124      troubleshooting steps. Check the documentation for information on
 125      troubleshooting. Adjusting settings or enabling debugging modes may give
 126      you more information about the issue.
 127  
 128  Reproducibility
 129  ===============
 130  
 131  The most important part of your report content is instructions on how to
 132  reproduce the issue. What did you do? If you do it again, does it still break?
 133  Does it depend on a specific browser? Can you reproduce the issue on
 134  `secure.phabricator.com`?
 135  
 136  Feel free to try to reproduce issues on the upstream install (which is kept near
 137  HEAD), within reason -- it's okay to make a few test objects if you're having
 138  trouble narrowing something down or want to check if updating might fix an
 139  issue.
 140  
 141  It is nearly impossible for us to resolve many issues if we can not reproduce
 142  them.
 143  
 144  Unreproducible Problems
 145  =======================
 146  
 147  Before we can fix a bug, we need to reproduce it. If we can't reproduce a
 148  problem, we can't tell if we've fixed it and often won't be able to figure out
 149  why it is occurring.
 150  
 151  Most problems reproduce easily, but some are more difficult to reproduce. We
 152  will generally make a reasonable effort to reproduce problems, but sometimes
 153  we will be unable to reproduce an issue.
 154  
 155  Many of these unreproducible issues turn out to be bizarre environmental
 156  problems that are unique to one user's install, and figuring out what is wrong
 157  takes a very long time with a lot of back and forth as we ask questions to
 158  narrow down the cause of the problem. When we eventually figure it out and fix
 159  it, few others benefit (in some cases, no one else). This sort of fishing
 160  expedition is not a good use of anyone's time, and it's very hard for us to
 161  prioritize solving these problems because they represent a huge effort for very
 162  little benefit.
 163  
 164  We will make a reasonable effort to reproduce problems, but can not help with
 165  issues which we can't reproduce. You can make sure we're able to help resolve
 166  your issue by generating clear reproduction steps.
 167  
 168  Create a Task in Maniphest
 169  ==========================
 170  
 171  If you're up to date, supported, have collected information about the problem,
 172  and have the best reproduction instructions you can come up with, you're ready
 173  to file an issue.
 174  
 175  We'll look at any issue report we can find (we monitor IRC, email, GitHub,
 176  StackOverflow, Quora, Facebook and Twitter), but the upstream Maniphest is
 177  the authoritative bug tracker and the best place to file:
 178  
 179  https://secure.phabricator.com/maniphest/task/create/
 180  
 181  If you don't want to file there (or, for example, your bug relates to being
 182  unable to log in or unable to file an issue in Maniphest) you can file on any
 183  other channel, but we can address reports much more effectively if they're
 184  filed against the upstream than if they're filed somewhere else.
 185  
 186  | Effectiveness | Filing Method |
 187  |---|---|
 188  | Best | Upstream Maniphest |
 189  | Okay | GitHub |
 190  | Ehhh | Quora, StackOverflow, Facebook, email, etc. |
 191  | What | Passive-aggressive tweet |
 192  
 193  If you have a quick question or want to discuss something before filing an
 194  issue, IRC is a great way to get a sanity check first. You can find information
 195  about IRC in @{article: Give Feedback! Get Support!}.
 196  
 197  Next Steps
 198  ==========
 199  
 200  Continue by:
 201  
 202    - learning about @{article: Contributing Feature Requests}; or
 203    - reading general support information in
 204      @{article: Give Feedback! Get Support!}; or
 205    - returning to the @{article:Contributor Introduction}.