mirror of
https://we.phorge.it/source/phorge.git
synced 2024-11-28 09:42:41 +01:00
5372fb772c
Summary: @btrahan asked about this but I gave the wrong answer. These currently do not turn into links. I think they might have in the past, but if they did the rule is a little weird and feels specific to my use. We can reexamine this at some point, but for now just make the links work in a normal, reasonable sort of way. Auditors: btrahan
205 lines
8.6 KiB
Text
205 lines
8.6 KiB
Text
@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;
|
|
- gather debugging information;
|
|
- 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.
|
|
|
|
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
|
|
`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.
|
|
|
|
Unreproducible Problems
|
|
=======================
|
|
|
|
Before we can fix a bug, we need to reproduce it. If we can't reproduce a
|
|
problem, we can't tell if we've fixed it and often won't be able to figure out
|
|
why it is occurring.
|
|
|
|
Most problems reproduce easily, but some are more difficult to reproduce. We
|
|
will generally make a reasonable effort to reproduce problems, but sometimes
|
|
we will be unable to reproduce an issue.
|
|
|
|
Many of these unreproducible issues turn out to be bizarre environmental
|
|
problems that are unique to one user's install, and figuring out what is wrong
|
|
takes a very long time with a lot of back and forth as we ask questions to
|
|
narrow down the cause of the problem. When we eventually figure it out and fix
|
|
it, few others benefit (in some cases, no one else). This sort of fishing
|
|
expedition is not a good use of anyone's time, and it's very hard for us to
|
|
prioritize solving these problems because they represent a huge effort for very
|
|
little benefit.
|
|
|
|
We will make a reasonable effort to reproduce problems, but can not help with
|
|
issues which we can't reproduce. You can make sure we're able to help resolve
|
|
your issue by generating clear reproduction steps.
|
|
|
|
Create a Task in Maniphest
|
|
==========================
|
|
|
|
If you're up to date, supported, have collected information about the problem,
|
|
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
|
|
other channel, 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 IRC 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}.
|