@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
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
+78
-137
+56
-10
src/docs/contributor/bug_reports.diviner
+56
-10
src/docs/contributor/bug_reports.diviner
···
15
15
- check the list of common fixes below;
16
16
- make sure Phabricator is up to date;
17
17
- make sure we support your setup;
18
+
- gather debugging information;
18
19
- explain how to reproduce the issue; and
19
20
- create a task in
20
21
[[ http://secure.phabricator.com/maniphest/task/create/ | Maniphest ]].
···
104
105
and followed the upstream install instructions on a normal computer, we're happy
105
106
to try to help.
106
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.
107
127
108
128
Reproducibility
109
129
===============
···
111
131
The most important part of your report content is instructions on how to
112
132
reproduce the issue. What did you do? If you do it again, does it still break?
113
133
Does it depend on a specific browser? Can you reproduce the issue on
114
-
`secure.phabricator.com`? Feel free to try to reproduce issues on the upstream
115
-
install (which is kept near HEAD), within reason -- it's okay to make a few test
116
-
objects if you're having trouble narrowing something down or want to check if
117
-
updating might fix an issue.
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.
118
140
119
141
It is nearly impossible for us to resolve many issues if we can not reproduce
120
-
them. For more information, see @{article: Give Feedback! Get Support!}.
142
+
them.
143
+
144
+
Unreproducible Problems
145
+
=======================
121
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.
122
167
123
168
Create a Task in Maniphest
124
169
==========================
125
170
126
-
If you're up to date, supported, and have the best reproduction instructions
127
-
you can come up with, you're ready to file an issue.
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.
128
174
129
175
We'll look at any issue report we can find (we monitor IRC, email, GitHub,
130
176
StackOverflow, Quora, Facebook and Twitter), but the upstream Maniphest is
···
133
179
https://secure.phabricator.com/maniphest/task/create/
134
180
135
181
If you don't want to file there (or, for example, your bug relates to being
136
-
unable to log in or unable to file an issue in Maniphest) you can file on any of
137
-
the other channels, but we can address reports much more effectively if they're
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
138
184
filed against the upstream than if they're filed somewhere else.
139
185
140
186
| Effectiveness | Filing Method |
···
146
192
147
193
If you have a quick question or want to discuss something before filing an
148
194
issue, IRC is a great way to get a sanity check first. You can find information
149
-
about these channels in @{article: Give Feedback! Get Support!}.
195
+
about IRC in @{article: Give Feedback! Get Support!}.
150
196
151
197
Next Steps
152
198
==========
+22
-127
src/docs/user/feedback.diviner
+22
-127
src/docs/user/feedback.diviner
···
5
5
How to give us feedback, report bugs, and request features, and get support for
6
6
problems with Phabricator.
7
7
8
-
= Overview =
9
-
10
-
We'd love to hear your feedback about Phabricator, whether it's good or bad. We
11
-
stay on top of bug reports and fix many of them within a day or two (and
12
-
sometimes within hours). The Phabricator roadmap is determined in large part by
13
-
user feedback and feature requests. Your feedback matters, will often have an
14
-
immediate short-term impact, and the project leads are actively listening to it.
8
+
Overview
9
+
========
15
10
16
-
We also try to provide a very high level of free support. If you have trouble
17
-
with anything or just don't understand how something works, ask us! We're happy
18
-
to help, and it's usually valuable for us because we can prevent the problem
19
-
in the code (or document it better) so future users don't hit it.
20
-
21
-
Some day we will no doubt grow callous and distant, but for now the community
22
-
is small enough that we can provide a high level of service and support to
23
-
everyone and still have plenty of time to write code.
24
-
25
-
If you're in the SF bay area, we're also happy to come onsite and help you set
26
-
things up, answer any questions you might have, or just hang out and tell
27
-
Facebook war stories.
11
+
We'd love to hear your feedback about Phabricator, whether it's good or bad. The
12
+
best ways to provide feedback and get support are:
28
13
29
-
The best ways to provide feedback are:
14
+
- For bug reports and feature requests, file a task in our task tracker,
15
+
Maniphest.
16
+
- For questions and real-time chat, join the IRC channel.
17
+
- If you just want to provide some quick feedback, you can tweet at
18
+
us ([[ http://twitter.com/phabricator | @phabricator ]]).
30
19
31
-
= Maniphest =
20
+
Bugs and Requests
21
+
=====================
32
22
33
23
The best way to report bugs and request features is through
34
-
[[http://secure.phabricator.com/maniphest/task/create/ | Maniphest]]. Just file
35
-
the bug/request and we'll handle everything else. (If it's time-sensitive or
36
-
blocking you, feel free to assign it to `epriestley`.) Feel free to file support
37
-
requests, general questions, or random feedback this way, too.
24
+
[[http://secure.phabricator.com/maniphest/task/create/ | Maniphest]]. For
25
+
information on filing good bug reports and feature requests, see:
38
26
39
-
= GitHub Issues =
40
-
41
-
You can also use
42
-
[[https://github.com/phacility/phabricator/issues/new | GitHub Issues]] if you
43
-
prefer.
27
+
- @{article:Filing Good Bug Reports}
28
+
- @{article:Filing Good Feature Requests}
44
29
45
-
= IRC =
30
+
IRC
31
+
==========
46
32
47
33
We're active in `#phabricator` on FreeNode, and it's the best place to ask
48
34
questions and get support.
49
35
50
-
= Email =
51
-
52
-
You can email us at `contact@phacility.com`.
53
-
54
-
= Filing Good Feature Requests =
55
-
56
-
When filing a feature request, please provide as much information as possible,
57
-
especially about what your use case is and why you want the feature. Explaining
58
-
what your larger goals are is very helpful, and lets us design better features.
59
-
Tell us what your problem is before you tell us your idea to solve it: sometimes
60
-
we can come up with a better approach to the problem, a slightly different
61
-
approach that solves more problems or helps other users, or a way to make the
62
-
problem go away entirely.
63
-
64
-
= Filing Good Bug Reports =
65
-
66
-
When filing a bug report, please provide as much information as possible. In
67
-
particular:
68
-
69
-
- If you received an error message, please please please provide it! It is
70
-
often incredibly useful. See @{article:Please Please Please}.
71
-
- The second most useful thing to us is reproduction steps. If at all
72
-
possible, provide a brief list of steps required to reproduce the problem.
73
-
- If something you didn't expect (other than a crash or obvious error)
74
-
happened, tell us what you expected and what actually happened.
75
-
76
-
We can fix clearly-described bugs with reproduction steps and error messages
77
-
much more quickly than vague bugs we can't reproduce.
78
-
79
-
In particular, if you don't include error messages, we need to ask you for error
80
-
messages. We will nearly always need to do this, and nearly always be unable
81
-
to continue until you provide them. You'll save everyone time if you spend a
82
-
few extra seconds copy/pasting them in the first place.
83
-
84
-
Generally, err on the side of giving us too much information. It's much quicker
85
-
and easier for us to filter out information that isn't relevant than it is to
86
-
go back and forth asking you to provide more details.
87
-
88
-
Tips:
89
-
90
-
- For issues with `arc`, you can get more information by running the command
91
-
with the `--trace` flag. For instance, run `arc diff --trace` instead of
92
-
`arc diff`. Including this output in your bug report is often helpful.
93
-
- For issues with Phabricator, check your webserver error logs for more
94
-
information. For Apache, this is usually `/var/log/httpd/error.log` or
95
-
`/var/log/apache2/error.log`.
96
-
- For issues with the UI, check your Javascript error console in your browser.
97
-
- Some other things, like daemons, have debug flags or troubleshooting steps
98
-
covered in their documentation. Enabling these flags may give you more
99
-
information about the problem.
100
-
101
-
= Unreproducible Problems =
102
-
103
-
Before we can fix a bug, we need to reproduce it. If we can't reproduce a
104
-
problem, we can't tell if we've fixed it and often won't be able to figure out
105
-
why it is occurring.
106
-
107
-
Most problems reproduce easily, but some are more difficult to reproduce. We
108
-
will generally make a reasonable effort to reproduce problems, but sometimes
109
-
we will be unable to reproduce an issue.
110
-
111
-
Many of these unreproducible issues turn out to be bizarre environmental
112
-
problems that are unique to one user's install, and figuring out what is wrong
113
-
takes a very long time with a lot of back and forth as we ask questions to
114
-
narrow down the cause of the problem. When we eventually figure it out and fix
115
-
it, few others benefit (in some cases, no one else). This sort of fishing
116
-
expedition is not a good use of anyone's time, and it's very hard for us to
117
-
prioritize solving these problems because they represent a huge effort for very
118
-
little benefit. These problems are a tiny fraction of requests (maybe 1-2%) but
119
-
take up the vast majority of our support effort (maybe 80%).
120
-
121
-
**If you want us to fix a bug we can't reproduce, you need to build us a working
122
-
reproduction case.** Generally, this means a `root` login on a machine where the
123
-
issue occurs. For example:
124
-
125
-
- Bring up a new machine (e.g., in EC2), install Phabricator on it, configure
126
-
it so the problem is reproducible, and then give us access to it.
127
-
- If the machine Phabricator is running on is nonessential/nonsensitive and
128
-
you're comfortable with us having root on it, give us credentials.
129
-
- If the issue is with Git, SVN or Mercurial, create a new empty repository,
130
-
add a commit or series of commits which replicate the issue, and give us
131
-
a zip/tarball of the repository as a reproduction case.
132
-
- If you're in the San Francisco bay area, we can probably swing by and fix
133
-
the issue onsite.
134
-
135
-
These are all fairly heavyweight and will take some time, but often //less//
136
-
of your time than a fishing expedition. If you can build a reproduction case,
137
-
there is a very high chance we can resolve your problem quickly.
138
-
139
-
Alternatively, you can pay us an enormous pile of money for some kind of
140
-
enterprise support thing and we'd be thrilled to go fishing with you for as long
141
-
as you remain solvent. Email us (see above) for specifics.
142
-
143
-
= Next Steps =
36
+
Next Steps
37
+
==========
144
38
145
39
Continue by:
146
40
147
-
- Filing a bug of feature request in
148
-
[[http://secure.phabricator.com/maniphest/task/create/ | Maniphest]]; or
41
+
- learning more about bug reports with @{article:Filing Good Bug Reports}; or
42
+
- learning more about feature requests with
43
+
@{article:Filing Good Feature Requests}; or
149
44
- contributing to Phabricator with @{article:Contributor Introduction}.