mirror of
https://we.phorge.it/source/phorge.git
synced 2024-12-23 05:50:55 +01:00
Narrow scope of support documentation
Summary: - Direct users to detailed bug report / feature reuqest documents. - Move "get more info" and "unreproducible problems" to bug reporting document. - Stop telling users to email us, and strongly encourage them to use primary channels. Test Plan: Read documentation. Reviewers: btrahan, chad Reviewed By: btrahan, chad Subscribers: epriestley Differential Revision: https://secure.phabricator.com/D10808
This commit is contained in:
epriestley
parent
bcb360ea2b
commit
31b4d39003
2 changed files with 78 additions and 137 deletions
|
|
@ -15,6 +15,7 @@ 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 ]].
|
||||
|
|
@ -104,6 +105,25 @@ 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
|
||||
===============
|
||||
|
|
@ -111,20 +131,46 @@ 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.
|
||||
`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. For more information, see @{article: Give Feedback! Get Support!}.
|
||||
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, and have the best reproduction instructions
|
||||
you can come up with, you're ready to file an issue.
|
||||
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
|
||||
|
|
@ -133,8 +179,8 @@ 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 of
|
||||
the other channels, but we can address reports much more effectively if they're
|
||||
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 |
|
||||
|
|
@ -146,7 +192,7 @@ filed against the upstream than if they're filed somewhere else.
|
|||
|
||||
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 these channels in @{article: Give Feedback! Get Support!}.
|
||||
about IRC in @{article: Give Feedback! Get Support!}.
|
||||
|
||||
Next Steps
|
||||
==========
|
||||
|
|
|
|||
|
|
@ -5,145 +5,40 @@
|
|||
How to give us feedback, report bugs, and request features, and get support for
|
||||
problems with Phabricator.
|
||||
|
||||
= Overview =
|
||||
Overview
|
||||
========
|
||||
|
||||
We'd love to hear your feedback about Phabricator, whether it's good or bad. We
|
||||
stay on top of bug reports and fix many of them within a day or two (and
|
||||
sometimes within hours). The Phabricator roadmap is determined in large part by
|
||||
user feedback and feature requests. Your feedback matters, will often have an
|
||||
immediate short-term impact, and the project leads are actively listening to it.
|
||||
We'd love to hear your feedback about Phabricator, whether it's good or bad. The
|
||||
best ways to provide feedback and get support are:
|
||||
|
||||
We also try to provide a very high level of free support. If you have trouble
|
||||
with anything or just don't understand how something works, ask us! We're happy
|
||||
to help, and it's usually valuable for us because we can prevent the problem
|
||||
in the code (or document it better) so future users don't hit it.
|
||||
- For bug reports and feature requests, file a task in our task tracker,
|
||||
Maniphest.
|
||||
- For questions and real-time chat, join the IRC channel.
|
||||
- If you just want to provide some quick feedback, you can tweet at
|
||||
us ([[ http://twitter.com/phabricator | @phabricator ]]).
|
||||
|
||||
Some day we will no doubt grow callous and distant, but for now the community
|
||||
is small enough that we can provide a high level of service and support to
|
||||
everyone and still have plenty of time to write code.
|
||||
|
||||
If you're in the SF bay area, we're also happy to come onsite and help you set
|
||||
things up, answer any questions you might have, or just hang out and tell
|
||||
Facebook war stories.
|
||||
|
||||
The best ways to provide feedback are:
|
||||
|
||||
= Maniphest =
|
||||
Bugs and Requests
|
||||
=====================
|
||||
|
||||
The best way to report bugs and request features is through
|
||||
[[http://secure.phabricator.com/maniphest/task/create/ | Maniphest]]. Just file
|
||||
the bug/request and we'll handle everything else. (If it's time-sensitive or
|
||||
blocking you, feel free to assign it to `epriestley`.) Feel free to file support
|
||||
requests, general questions, or random feedback this way, too.
|
||||
[[http://secure.phabricator.com/maniphest/task/create/ | Maniphest]]. For
|
||||
information on filing good bug reports and feature requests, see:
|
||||
|
||||
= GitHub Issues =
|
||||
- @{article:Filing Good Bug Reports}
|
||||
- @{article:Filing Good Feature Requests}
|
||||
|
||||
You can also use
|
||||
[[https://github.com/phacility/phabricator/issues/new | GitHub Issues]] if you
|
||||
prefer.
|
||||
|
||||
= IRC =
|
||||
IRC
|
||||
==========
|
||||
|
||||
We're active in `#phabricator` on FreeNode, and it's the best place to ask
|
||||
questions and get support.
|
||||
|
||||
= Email =
|
||||
|
||||
You can email us at `contact@phacility.com`.
|
||||
|
||||
= Filing Good Feature Requests =
|
||||
|
||||
When filing a feature request, please provide as much information as possible,
|
||||
especially about what your use case is and why you want the feature. Explaining
|
||||
what your larger goals are is very helpful, and lets us design better features.
|
||||
Tell us what your problem is before you tell us your idea to solve it: sometimes
|
||||
we can come up with a better approach to the problem, a slightly different
|
||||
approach that solves more problems or helps other users, or a way to make the
|
||||
problem go away entirely.
|
||||
|
||||
= Filing Good Bug Reports =
|
||||
|
||||
When filing a bug report, please provide as much information as possible. In
|
||||
particular:
|
||||
|
||||
- If you received an error message, please please please provide it! It is
|
||||
often incredibly useful. See @{article:Please Please Please}.
|
||||
- The second most useful thing to us is reproduction steps. If at all
|
||||
possible, provide a brief list of steps required to reproduce the problem.
|
||||
- If something you didn't expect (other than a crash or obvious error)
|
||||
happened, tell us what you expected and what actually happened.
|
||||
|
||||
We can fix clearly-described bugs with reproduction steps and error messages
|
||||
much more quickly than vague bugs we can't reproduce.
|
||||
|
||||
In particular, if you don't include error messages, we need to ask you for error
|
||||
messages. We will nearly always need to do this, and nearly always be unable
|
||||
to continue until you provide them. You'll save everyone time if you spend a
|
||||
few extra seconds copy/pasting them in the first place.
|
||||
|
||||
Generally, err on the side of giving us too much information. It's much quicker
|
||||
and easier for us to filter out information that isn't relevant than it is to
|
||||
go back and forth asking you to provide more details.
|
||||
|
||||
Tips:
|
||||
|
||||
- For issues with `arc`, you can get more information by running the command
|
||||
with the `--trace` flag. For instance, run `arc diff --trace` instead of
|
||||
`arc diff`. Including this output in your bug report is often helpful.
|
||||
- For issues with Phabricator, check your webserver error logs for more
|
||||
information. For Apache, this is usually `/var/log/httpd/error.log` or
|
||||
`/var/log/apache2/error.log`.
|
||||
- For issues with the UI, check your Javascript error console in your browser.
|
||||
- Some other things, like daemons, have debug flags or troubleshooting steps
|
||||
covered in their documentation. Enabling these flags may give you more
|
||||
information about the problem.
|
||||
|
||||
= 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. These problems are a tiny fraction of requests (maybe 1-2%) but
|
||||
take up the vast majority of our support effort (maybe 80%).
|
||||
|
||||
**If you want us to fix a bug we can't reproduce, you need to build us a working
|
||||
reproduction case.** Generally, this means a `root` login on a machine where the
|
||||
issue occurs. For example:
|
||||
|
||||
- Bring up a new machine (e.g., in EC2), install Phabricator on it, configure
|
||||
it so the problem is reproducible, and then give us access to it.
|
||||
- If the machine Phabricator is running on is nonessential/nonsensitive and
|
||||
you're comfortable with us having root on it, give us credentials.
|
||||
- If the issue is with Git, SVN or Mercurial, create a new empty repository,
|
||||
add a commit or series of commits which replicate the issue, and give us
|
||||
a zip/tarball of the repository as a reproduction case.
|
||||
- If you're in the San Francisco bay area, we can probably swing by and fix
|
||||
the issue onsite.
|
||||
|
||||
These are all fairly heavyweight and will take some time, but often //less//
|
||||
of your time than a fishing expedition. If you can build a reproduction case,
|
||||
there is a very high chance we can resolve your problem quickly.
|
||||
|
||||
Alternatively, you can pay us an enormous pile of money for some kind of
|
||||
enterprise support thing and we'd be thrilled to go fishing with you for as long
|
||||
as you remain solvent. Email us (see above) for specifics.
|
||||
|
||||
= Next Steps =
|
||||
Next Steps
|
||||
==========
|
||||
|
||||
Continue by:
|
||||
|
||||
- Filing a bug of feature request in
|
||||
[[http://secure.phabricator.com/maniphest/task/create/ | Maniphest]]; or
|
||||
- learning more about bug reports with @{article:Filing Good Bug Reports}; or
|
||||
- learning more about feature requests with
|
||||
@{article:Filing Good Feature Requests}; or
|
||||
- contributing to Phabricator with @{article:Contributor Introduction}.
|
||||
|
|
|
|||
Loading…
Reference in a new issue