@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
Provide "Reproduction Steps" docs and separate "Version" doc
Summary: I know this is ultimately pointless but feel better about pushing back on users when there is no possible way they could be acting in good faith.
Test Plan: Read documents.
Reviewers: chad
Reviewed By: chad
Differential Revision: https://secure.phabricator.com/D15518
+316
-35
+7
-35
src/docs/contributor/bug_reports.diviner
+7
-35
src/docs/contributor/bug_reports.diviner
···
8
8
9
9
IMPORTANT: When filing a bug report, you **MUST** include reproduction
10
10
instructions. We can not help fix bugs we can not reproduce, and will not
11
-
accept reports which omit reproduction instructions. See below for details.
11
+
accept reports which omit reproduction instructions.
12
12
13
+
For help, see @{article:Providing Reproduction Steps}.
13
14
14
15
Overview
15
16
========
···
69
70
@{article:Upgrading Phabricator}.
70
71
71
72
**If you can not update** for some reason, please include the version of
72
-
Phabricator you are running when you file a report. You can find the version in
73
-
{nav Config > Versions} in the web UI.
73
+
Phabricator you are running when you file a report.
74
74
75
-
(The version is just the Git hash of your local HEAD, so you can also find it
76
-
by running `git show` in `phabricator/` and looking at the first line of
77
-
output.)
75
+
For help, see @{article:Providing Version Information}.
78
76
79
77
80
78
Supported Issues
···
86
84
**We can NOT help you with issues we can not reproduce.** It is critical that
87
85
you explain how to reproduce the issue when filing a report.
88
86
87
+
For help, see @{article:Providing Reproduction Steps}.
88
+
89
89
**We do NOT support prototype applications.** If you're running into an issue
90
90
with a prototype application, you're on your own. For more information about
91
91
prototype applications, see @{article:User Guide: Prototype Applications}.
···
144
144
Does it depend on a specific browser? Can you reproduce the issue on
145
145
`secure.phabricator.com`?
146
146
147
-
Feel free to try to reproduce issues on the upstream install (which is kept near
148
-
HEAD), within reason -- it's okay to make a few test objects if you're having
149
-
trouble narrowing something down or want to check if updating might fix an
150
-
issue.
151
-
152
147
It is nearly impossible for us to resolve many issues if we can not reproduce
153
148
them. We will not accept reports which do not contain the information required
154
149
to reproduce problems.
155
150
156
-
157
-
Unreproducible Problems
158
-
=======================
159
-
160
-
Before we can fix a bug, we need to reproduce it. If we can't reproduce a
161
-
problem, we can't tell if we've fixed it and often won't be able to figure out
162
-
why it is occurring.
163
-
164
-
Most problems reproduce easily, but some are more difficult to reproduce. We
165
-
will generally make a reasonable effort to reproduce problems, but sometimes
166
-
we will be unable to reproduce an issue.
167
-
168
-
Many of these unreproducible issues turn out to be bizarre environmental
169
-
problems that are unique to one user's install, and figuring out what is wrong
170
-
takes a very long time with a lot of back and forth as we ask questions to
171
-
narrow down the cause of the problem. When we eventually figure it out and fix
172
-
it, few others benefit (in some cases, no one else). This sort of fishing
173
-
expedition is not a good use of anyone's time, and it's very hard for us to
174
-
prioritize solving these problems because they represent a huge effort for very
175
-
little benefit.
176
-
177
-
We will make a reasonable effort to reproduce problems, but can not help with
178
-
issues which we can't reproduce. You can make sure we're able to help resolve
179
-
your issue by generating clear reproduction steps.
151
+
For help, see @{article:Providing Reproduction Steps}.
180
152
181
153
182
154
Create a Task in Maniphest
+252
src/docs/contributor/reproduction_steps.diviner
+252
src/docs/contributor/reproduction_steps.diviner
···
1
+
@title Providing Reproduction Steps
2
+
@group detail
3
+
4
+
Describes how to provide reproduction steps.
5
+
6
+
Overview
7
+
========
8
+
9
+
When you submit a bug report about Phabricator, you **MUST** include
10
+
reproduction steps. We can not help you with bugs we can not reproduce, and
11
+
will not accept reports which omit reproduction steps or have incomplete or
12
+
insufficient instructions.
13
+
14
+
This document explains what we're looking for in good reproduction steps.
15
+
Briefly:
16
+
17
+
- Reproduction steps must allow us to reproduce the problem locally on a
18
+
clean, up-to-date install of Phabricator.
19
+
- Reproduction should be as simple as possible.
20
+
21
+
Good reproduction steps can take time to write out clearly, simplify, and
22
+
verify. As a reporter, we expect you to shoulder as much of this burden as you
23
+
can, to make make it easy for us to reproduce and resolve bugs.
24
+
25
+
We do not have the resources to pursue reports with limited, inaccurate, or
26
+
incomplete reproduction steps, and will not accept them. These reports require
27
+
large amounts of our time and are often fruitless.
28
+
29
+
30
+
Example Reproduction Steps
31
+
==========================
32
+
33
+
Here's an example of what good reproduction steps might look like:
34
+
35
+
---
36
+
37
+
Reproduction steps:
38
+
39
+
- Click "Create Event" in Calendar.
40
+
- Fill in the required fields with any text (name, description, etc).
41
+
- Set an invalid time for one of the dates, like the meaningless string
42
+
"Tea Time". This is not valid, so we're expecting an error when we
43
+
submit the form.
44
+
- Click "Create" to save the event.
45
+
46
+
Expected result:
47
+
48
+
- Form reloads with an error message about the specific mistake.
49
+
- All field values are retained.
50
+
51
+
Actual result:
52
+
53
+
- Form reloads with an error message about the specific mistake.
54
+
- Most values are discarded, so I have to re-type the name, description, etc.
55
+
56
+
---
57
+
58
+
These steps are **complete** and **self-contained**: anyone can reproduce the
59
+
issue by following these steps. These steps are **clear** and **easy to
60
+
follow**. These steps are also simple and minimal: they don't include any
61
+
extra unnecessary steps.
62
+
63
+
Finally, these steps explain what the reporter expected to happen, what they
64
+
observed, and how those behaviors differ. This isn't as important when the
65
+
observation is an obvious error like an exception, but can be important if a
66
+
behavior is merely odd or ambiguous.
67
+
68
+
69
+
Reliable Reproduction
70
+
=====================
71
+
72
+
When you file a bug report, the first thing we do to fix it is to try to
73
+
reproduce the problem locally on an up-to-date install of Phabricator. We will
74
+
do this by following the steps you provide. If we can recreate the issue
75
+
locally, we can almost always resolve the problem (often very promptly).
76
+
77
+
However, many reports do not have enough information, are missing important
78
+
steps, or rely on data (like commits, users, other projects, permission
79
+
settings, feed stories, etc) that we don't have access to. We either can't
80
+
follow these steps, or can't reproduce issues by following them.
81
+
82
+
Reproduction steps must be complete and self-contained, and must allow
83
+
**anyone** to reproduce the issue on a new, empty install of Phabricator. If
84
+
the bug you're seeing depends on data or configuration which would not be
85
+
present on a new install, you need to include that information in your steps.
86
+
87
+
For example, if you're seeing an issue which depends on a particular policy
88
+
setting or configuration setting, you need to include instructions for creating
89
+
the policy or adjusting the setting in your steps.
90
+
91
+
92
+
Getting Started
93
+
===============
94
+
95
+
To generate reproduction steps, first find a sequence of actions which
96
+
reproduce the issue you're seeing reliably.
97
+
98
+
Next, write down everything you did as clearly as possible. Make sure each step
99
+
is self-contained: anyone should be able to follow your steps, without access
100
+
to private or proprietary data.
101
+
102
+
Now, to verify that your steps provide a complete, self-contained way to
103
+
reproduce the issue, follow them yourself on a new, empty, up-to-date instance
104
+
of Phabricator.
105
+
106
+
If you can't easily start an empty instance locally, you can launch an empty
107
+
instance on Phacility in about 60 seconds (see the "Resources" section for
108
+
details).
109
+
110
+
If you can follow your steps and reproduce the issue on a clean instance,
111
+
we'll probably be able to follow them and reproduce the issue ourselves.
112
+
113
+
If you can't follow your steps because they depend on information which is not
114
+
available on a clean instance (for example, a certain config setting), rewrite
115
+
them to include instrutions to create that information (for example, adjusting
116
+
the config to the problematic value).
117
+
118
+
If you follow your instructions but the issue does not reproduce, the issue
119
+
might already be fixed. Make sure your install is up to date.
120
+
121
+
If your install is up to date and the issue still doesn't reproduce on a clean
122
+
install, your reproduction steps are missing important information. You need to
123
+
figure out what key element differs between your install and the clean install.
124
+
125
+
Once you have working reproduction steps, your steps may have details which
126
+
aren't actually necessary to reproduce the issue. You may be able to simplify
127
+
them by removing some steps or describing steps more narrowly. For help, see
128
+
"Simplifying Steps" below.
129
+
130
+
131
+
Resources
132
+
=========
133
+
134
+
We provide some resources which can make it easier to start building steps, or
135
+
to simplify steps.
136
+
137
+
**Phacility Test Instances**: You can launch a new, up-to-date instance of
138
+
Phabricator on Phacility in about a minute at <https://admin.phacility.com>.
139
+
These instances run `stable`.
140
+
141
+
You can use these instances to make sure that issues haven't already been
142
+
fixed, that they reproduce on a clean install, or that your steps are really
143
+
complete, and that the root cause isn't custom code or local extensions. Using
144
+
a test instance will avoid disrupting other users on your install.
145
+
146
+
**Test Repositories**: There are several test repositories on
147
+
`secure.phabriactor.com` which you can push commits to if you need to build
148
+
an example to demonstrate a problem.
149
+
150
+
For example, if you're seeing an issue with a certain filename but the commit
151
+
where the problem occurs is in a proprietary internal repository, push a commit
152
+
that affects a file with a similar name to a test repository, then reproduce
153
+
against the test data. This will allow you to generate steps which anyone can
154
+
follow.
155
+
156
+
157
+
Simplifying Steps
158
+
=================
159
+
160
+
If you aren't sure how to simplify reproduction steps, this section has some
161
+
advice.
162
+
163
+
In general, you'll simplify reproduction steps by first finding a scenario
164
+
where the issue reproduces reliably (a "bad" case) and a second, similar
165
+
situation where it does not reproduce (a "good" case). Once you have a "bad"
166
+
case and a "good" case, you'll change the scenarios step-by-step to be more
167
+
similar to each other, until you have two scenarios which differ only a very
168
+
small amount. This remaining difference usually points clearly at the root
169
+
cause of the issue.
170
+
171
+
For example, suppose you notice that you get an error if you commit a file
172
+
named `A Banana.doc`, but not if you commit a file named `readme.md`. In
173
+
this case, `A Banana.doc` is your "bad" case and `readme.md` is your "good"
174
+
case.
175
+
176
+
There are several differences between these file names, and any of them might
177
+
be causing the problem. To narrow this down, you can try making the scenarios
178
+
more similar. For example, do these files work?
179
+
180
+
- `A_Banana.doc` - Problem with spaces?
181
+
- `A Banana.md` - File extension issue?
182
+
- `A Ban.doc` - Path length issue?
183
+
- `a banana.doc` - Issue with letter case?
184
+
185
+
Some of these probably work, while others might not. These could lead you to a
186
+
smaller case which reproduces the problem, which might be something like this:
187
+
188
+
- Files like `a b`, which contain spaces, do not work.
189
+
- Files like `a.doc`, which have the `.doc` extension, do not work.
190
+
- Files like `AAAAAAAAAA`, which have more than 9 letters, do not work.
191
+
- Files like `A`, which have uppercase letters, do not work.
192
+
193
+
With a simpler reproduction scenario, you can simplify your steps to be more
194
+
tailored and mimimal. This will help us pointpoint the issue more quickly and
195
+
be more certain that we've understood and resolved it.
196
+
197
+
It is more important that steps be complete than that they be simple, and it's
198
+
acceptable to submit complex instructions if you have difficulty simplifying
199
+
them, so long as they are complete, self-contained, and accurately reproduce
200
+
the issue.
201
+
202
+
203
+
Things to Avoid
204
+
===============
205
+
206
+
These are common mistakes when providing reproduction instructions:
207
+
208
+
**Insufficient Information**: The most common issue we see is instructions
209
+
which do not have enough information: they are missing critical details which
210
+
are necessary in order to follow them on a clean install.
211
+
212
+
**Inaccurate Steps**: The second most common issue we see is instructions
213
+
which do not actually reproduce a problem when followed on a clean, up-to-date
214
+
install. Verify your steps by testing them.
215
+
216
+
**Private Information**: Some users provide reports which hinge on the
217
+
particulars of private commits in proprietary repositories we can not access.
218
+
This is not useful, because we can not examine the underlying commit to figure
219
+
out why it is causing an issue.
220
+
221
+
Instead, reproduce the issue in a public repository. There are several test
222
+
repositories available which you can push commits to in order to construct a
223
+
reproduction case.
224
+
225
+
**Screenshots**: Screenshots can be helpful to explain a set of steps or show
226
+
what you're seeing, but they usually aren't sufficient on their own because
227
+
they don't contain all the information we need to reproduce them.
228
+
229
+
For example, a screenshot may show a particular policy or object, but not have
230
+
enough information for us rebuild a similar object locally.
231
+
232
+
233
+
Alternatives
234
+
============
235
+
236
+
If you have an issue which you can't build reproduction steps for, or which
237
+
only reproduces in your environment, or which you don't want to narrow down
238
+
to a minimal reproduction case, we can't accept it as a bug report. These
239
+
issues are tremendously time consuming for us to pursue and rarely benefit
240
+
more than one install.
241
+
242
+
If the issue is important but falls outside the scope of permissible bug
243
+
reports, we're happy to provide more tailored support at consulting rates. See
244
+
[[ https://secure.phabricator.com/w/consulting/ | Consulting ]] for details.
245
+
246
+
247
+
Next Steps
248
+
==========
249
+
250
+
Continue by:
251
+
252
+
- returning to @{article:Contributing Bug Reports}.
+57
src/docs/contributor/version.diviner
+57
src/docs/contributor/version.diviner
···
1
+
@title Providing Version Information
2
+
@group detail
3
+
4
+
How to provide version information with reports made to the upstream.
5
+
6
+
Overview
7
+
========
8
+
9
+
When you submit a bug report, we require that you include version information.
10
+
11
+
Despite our insistence that users update before reporting issues, many reports
12
+
we receive describe issues which have already been resolved. Including version
13
+
information in your report allows us to quickly determine that you are out of
14
+
date and that updating will fix your issue.
15
+
16
+
That said, your report must also include reproduction steps, and you should be
17
+
unable to generate valid reproduction steps for an issue which has already been
18
+
resolved because valid reproduction steps must also reproduce against a clean,
19
+
up-to-date install. See @{article:Providing Reproduction Steps} for details.
20
+
21
+
22
+
Phabricator Version
23
+
===================
24
+
25
+
To get Phabricator version information:
26
+
27
+
- Go to the {nav Config} application. You can type "Config" into the global
28
+
search box, or navigate to `https://your.install.com/config/`. You must
29
+
be an administrator to access this application.
30
+
- Click {nav Versions} in the left menu.
31
+
- Copy and paste all of the information on the page into your report.
32
+
33
+
34
+
Arcanist Version
35
+
================
36
+
37
+
To get Arcanist version information:
38
+
39
+
- Run `arc version`.
40
+
- Copy and paste all of the output into your report.
41
+
42
+
43
+
Other Versions
44
+
==============
45
+
46
+
In general, we use `git` commit hashes as version identifiers, so you can
47
+
identify the version of something by running `git show` and copy/pasting the
48
+
hash from the output. This may be useful if you're encountering an issue which
49
+
prevents you from reaching the version reporting screen.
50
+
51
+
52
+
Next Steps
53
+
==========
54
+
55
+
Continue by:
56
+
57
+
- returning to @{article:Contributing Bug Reports}.