@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
Write bug report, feature request and code contribution guides
Summary:
Fixes T6347. This refines the "contributor guide" documents to basically lock down support further. Notable changes in policy:
- Bugs: Emphasis on reproduction steps, strong emphasis on using Maniphest. Emphasis on what we support.
- Features: Emphasis on describing problems instead of solutions, emphasis on realistic expecations about timelines. Strong emphasis on using Maniphest.
- Code: Strong emphasis on coordinating with us first. No GitHub pull requests. Emphasis on us ignoring contributions we don't have time to deal with. Suggests local forks.
Test Plan: Read these through; let me generate them and take some screenshots for easier reading.
Reviewers: btrahan, chad
Reviewed By: chad
Subscribers: epriestley
Maniphest Tasks: T6347
Differential Revision: https://secure.phabricator.com/D10764
+619
-64
+3
src/docs/book/contributor.book
+3
src/docs/book/contributor.book
+159
src/docs/contributor/bug_reports.diviner
+159
src/docs/contributor/bug_reports.diviner
···
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
+
- explain how to reproduce the issue; and
19
+
- create a task in
20
+
[[ http://secure.phabricator.com/maniphest/task/create/ | Maniphest ]].
21
+
22
+
The rest of this article walks through these points in detail.
23
+
24
+
If you have a feature request (not a bug report), see
25
+
@{article:Contributing Feature Requests} for a more tailored guide.
26
+
27
+
For general information on contributing to Phabricator, see
28
+
@{article:Contributor Introduction}.
29
+
30
+
Common Fixes
31
+
============
32
+
33
+
Before you file a report, here are some common solutions to problems:
34
+
35
+
- **Update Phabricator**: We receive a lot of bug reports about issues we have
36
+
already fixed in HEAD. Updating often resolves issues. It is common for
37
+
issues to be fixed in less than 24 hours, so even if you've updated recently
38
+
you should update again. If you aren't sure how to update, see the next
39
+
section.
40
+
- **Update Libraries**: Make sure `libphutil/`, `arcanist/` and
41
+
`phabricator/` are all up to date. Users often update `phabricator/` but
42
+
forget to update `arcanist/` or `libphutil/`. When you update, make sure you
43
+
update all three libraries.
44
+
- **Restart Apache or PHP-FPM**: Phabricator uses caches which don't get
45
+
reset until you restart Apache or PHP-FPM. After updating, make sure you
46
+
restart.
47
+
48
+
49
+
Update Phabricator
50
+
==================
51
+
52
+
Before filing a bug, make sure you are up to date. We receive many bug reports
53
+
for issues we have already fixed, and even if we haven't fixed an issue we'll
54
+
be able to resolve it more easily if you file a report based on HEAD. (For
55
+
example, an old stack trace may not have the right line numbers, which will
56
+
make it more difficult for us to figure out what's going wrong.)
57
+
58
+
To update Phabricator, use a script like this one:
59
+
60
+
http://www.phabricator.com/rsrc/install/update_phabricator.sh
61
+
62
+
This script will require some adjustments depending on how your setup is
63
+
configured, which webserver you are using, etc.
64
+
65
+
**If you can not update** for some reason, please include the version of
66
+
Phabricator you are running in your report. The version is just the Git hash
67
+
of your local HEAD. You can find the version by running `git show` in
68
+
`phabricator/` and copy/pasting the first line of output, or by browsing to
69
+
{nav Config > All Settings} in the web UI and copy/pasting the information
70
+
at the top.
71
+
72
+
73
+
Supported Issues
74
+
================
75
+
76
+
Before filing a bug, make sure you're filing an issue against something we
77
+
support.
78
+
79
+
**We do NOT support prototype applications.** If you're running into an issue
80
+
with a prototype application, you're on your own. For more information about
81
+
prototype applications, see @{article:User Guide: Prototype Applications}.
82
+
83
+
**We do NOT support third-party packages or instructions.** If you installed
84
+
Phabricator (or configured some aspect of it) using a third-party package or by
85
+
following a third-party guide (like a blog post), we can not help you.
86
+
Phabricator changes quickly and third-party information is unreliable and often
87
+
falls out of date. Contact the maintainer of the package or guide you used,
88
+
or reinstall following the upstream instructions.
89
+
90
+
**We do NOT support custom code development or third-party libraries.** If
91
+
you're writing an extension, you're on your own. We provide some documentation,
92
+
but can not help you with extension or library development. If you downloaded a
93
+
library from somewhere, contact the library maintainer.
94
+
95
+
**We do NOT support bizarre environments.** If your issue is specific to an
96
+
unusual installation environment, we generally will not help you find a
97
+
workaround. Install Phabricator in a normal environment instead. Examples of
98
+
unusual environments are shared hosts, nontraditional hosts (gaming consoles,
99
+
storage appliances), and hosts with unusually tight resource constraints. The
100
+
vast majority of users run Phabricator in normal environments (modern computers
101
+
with root access) and these are the only environments we support.
102
+
103
+
Otherwise, if you're having an issue with a supported first-party application
104
+
and followed the upstream install instructions on a normal computer, we're happy
105
+
to try to help.
106
+
107
+
108
+
Reproducibility
109
+
===============
110
+
111
+
The most important part of your report content is instructions on how to
112
+
reproduce the issue. What did you do? If you do it again, does it still break?
113
+
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.
118
+
119
+
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!}.
121
+
122
+
123
+
Create a Task in Maniphest
124
+
==========================
125
+
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.
128
+
129
+
We'll look at any issue report we can find (we monitor IRC, email, GitHub,
130
+
StackOverflow, Quora, Facebook and Twitter), but the upstream Maniphest is
131
+
the authoritative bug tracker and the best place to file:
132
+
133
+
https://secure.phabricator.com/maniphest/task/create/
134
+
135
+
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
138
+
filed against the upstream than if they're filed somewhere else.
139
+
140
+
| Effectiveness | Filing Method |
141
+
|---|---|
142
+
| Best | Upstream Maniphest |
143
+
| Okay | GitHub |
144
+
| Ehhh | Quora, StackOverflow, Facebook, email, etc. |
145
+
| What | Passive-aggressive tweet |
146
+
147
+
If you have a quick question or want to discuss something before filing an
148
+
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!}.
150
+
151
+
Next Steps
152
+
==========
153
+
154
+
Continue by:
155
+
156
+
- learning about @{article: Contributing Feature Requests}; or
157
+
- reading general support information in
158
+
@{article: Give Feedback! Get Support!}; or
159
+
- returning to the @{article:Contributor Introduction}.
+12
-64
src/docs/contributor/contrib_intro.diviner
+12
-64
src/docs/contributor/contrib_intro.diviner
···
41
41
things right away, but knowing about issues users are encountering or
42
42
features they'd like to see improves our ability to plan and prioritize.
43
43
For ways to do this, see @{article:Give Feedback! Get Support!}
44
+
- For details on reporting bugs, see @{article:Contributing Bug Reports}.
45
+
- For details on requesting features, see @{article:Contributing Feature
46
+
Requests}.
44
47
- Give us feedback on planned features. Most of what we'll build in the next
45
48
6-12 months currently exists on the [[ Roadmap ]] or in Maniphest. Telling
46
49
us about use cases you have can help us build better products when the time
···
53
56
@{article:Give Feedback! Get Support!}
54
57
55
58
If all of this sounds nice but you really just want to write some code, that's
56
-
awesome too. The rest of this document (and the other articles in this section
57
-
of the documentation) can help you get started.
58
-
59
-
= Legal Stuff =
60
-
61
-
Before we can accept source code contributions, you need to submit a
62
-
[[ https://secure.phabricator.com/L28 | Contributor License Agreement ]]. Your
63
-
changes can not be accepted until you sign the agreement.
64
-
65
-
If you haven't signed it by the time you send changes for review, you'll be
66
-
reminded to sign it at that time.
67
-
68
-
If you're submitting work on behalf of a company (like your employer), the
69
-
company can sign the [[ https://secure.phabricator.com/L30 | Corporate
70
-
Contributor License Agreement ]] instead.
71
-
72
-
Both agreements are substantially similar to the Apache Foundation's CLAs. They
73
-
protect Phacility and users of Phabricator by making sure we have permission to
74
-
distribute your changes under an open source license.
75
-
76
-
= Not Sure Where To Get Started? =
77
-
78
-
Because we're usually quick to fix easy bugs and issues, we often don't have a
79
-
very good backlog of starter tasks.
80
-
81
-
You can try searching in Maniphest for tasks tagged with "Easy", which might
82
-
have something, but a lot of time this list is small and the tasks on it aren't
83
-
very fun or interesting even if they aren't technically too difficult.
84
-
85
-
In general, the best way to contribute is to come to us with a problem you
86
-
encountered or something you're interested in building, and then work with us
87
-
to find a solution to it or a plan to build it. We can help turn a hacky patch
88
-
into something that's upstreamable, and you'll get a fix or feature you want.
89
-
90
-
You can also look though the rest of the open tasks for something more
91
-
substantive that you're interested in. This will give you a better chance of
92
-
finding something that's relevant to you, but many tasks are large or blocked
93
-
by other large tasks.
94
-
95
-
If you do find something, feel free to leave a comment like "I'm interested in
96
-
working on this, is this something I could reasonably help with?". We're happy
97
-
to walk through things, break larger tasks down into more detail, provide
98
-
pointers to similar changes and the right places in the codebase to get started,
99
-
and generally figure out how to attack a problem.
100
-
101
-
You can also just come find us in IRC and ask how to get started.
102
-
103
-
= Submitting Patches =
104
-
105
-
To submit patches against libphutil, Arcanist or Phabricator, create a commit
106
-
and use `arc` to send it for review (probably with `epriestley` as a reviewer):
107
-
108
-
$ arc diff
109
-
110
-
You can also submit a pull request on GitHub, but Differential is strongly
111
-
preferred.
59
+
awesome too. To get started with contributing code, see
60
+
@{article:Contributing Code}.
112
61
113
-
= Suggested Reading =
62
+
Next Steps
63
+
==========
114
64
115
-
You should read the relevant coding convention documents before you submit a
116
-
change. If you're a new contributor, you don't need to worry about this too
117
-
much. Just try to make your code look similar to the code around it, and we
118
-
can help you through the details during review.
65
+
Continue by:
119
66
120
-
- @{article:General Coding Standards} (for all languages)
121
-
- @{article:PHP Coding Standards} (for PHP)
122
-
- @{article:Javascript Coding Standards} (for Javascript)
67
+
- learning about bug reports in @{article:Contributing Bug Reports};
68
+
- learning about feature requests in @{article:Contributing Feature Requests};
69
+
- learning about code contributions in @{article:Contributing Code}; or
70
+
- getting in touch with @{article:Give Feedback! Get Support!}
+256
src/docs/contributor/contributing_code.diviner
+256
src/docs/contributor/contributing_code.diviner
···
1
+
@title Contributing Code
2
+
@group detail
3
+
4
+
Describes how to contribute code to Phabricator.
5
+
6
+
Overview
7
+
========
8
+
9
+
If you're planning to send a patch to Phabricator, this guide can help you
10
+
through the process. The most important parts of contributing code to
11
+
Phabricator are:
12
+
13
+
- File a task with a bug report or feature request //before// you write code.
14
+
- We rarely accept patches which we haven't discussed first.
15
+
- We do not accept patches against prototype applications.
16
+
- You must sign the CLA.
17
+
- We do not accept GitHub pull requests.
18
+
- Some alternative approaches are available if your change isn't something
19
+
we want to bring upstream.
20
+
21
+
The rest of this article describes these points in more detail, and then
22
+
provides guidance on writing and submitting patches.
23
+
24
+
If you just want to contribute some code but don't have a specific bug or
25
+
feature in mind, see the bottom of this document for tips on finding ways to get
26
+
started.
27
+
28
+
For general information on contributing to Phabricator, see
29
+
@{article:Contributor Introduction}.
30
+
31
+
32
+
Coordinate First
33
+
================
34
+
35
+
Before sending code, you should file a bug report or feature request describing
36
+
what you'd like to write. For details on how to do this, see these articles:
37
+
38
+
- @{article:Contributing Bug Reports}
39
+
- @{article:Contributing Feature Requests}
40
+
41
+
When you file a task, mention that you'd like to write the code to fix it. We
42
+
can help contextualize your request or bug and guide you through writing an
43
+
upstreamable patch, provided it's something that's upstreamable. If it isn't
44
+
upstreamable, we can let you know what the issues are and help find another
45
+
plan of attack.
46
+
47
+
You don't have to file first (for example, if you spot a misspelling it's
48
+
normally fine to just send a diff), but for anything even moderately complex
49
+
you're strongly encouraged to file first and coordinate with the upstream.
50
+
51
+
52
+
Rejecting Patches
53
+
=================
54
+
55
+
If you send us a patch without coordinating it with us first, it will probably
56
+
be immediately rejected, or sit in limbo for a long time and eventually be
57
+
rejected. The reasons we do this vary from patch to patch, but some of the most
58
+
common reasons are:
59
+
60
+
**Unjustifiable Costs**: We support code in the upstream forever. Support is
61
+
enormously expensive and takes up a huge amount of our time. The cost to support
62
+
a change over its lifetime is often 10x or 100x or 1000x greater than the cost
63
+
to write the first version of it. Many uncoordinated patches we receive are
64
+
"white elephants", which would cost much more to maintain than the value they
65
+
provide.
66
+
67
+
As an author, it may look like you're giving us free work and we're rejecting it
68
+
as too expensive, but this viewpoint doesn't align with the reality of a large
69
+
project which is actively supported by a small, experienced team. Writing code
70
+
is cheap; maintaining it is expensive.
71
+
72
+
By coordinating with us first, you can make sure the patch is something we
73
+
consider valuable enough to put long-term support resources behind, and that
74
+
you're building it in a way that we're comfortable taking over.
75
+
76
+
**Not a Good Fit**: Many patches aren't good fits for the upstream: they
77
+
implement features we simply don't want. You can find more information in
78
+
@{article:Contributing Feature Requests}. Coordinating with us first helps
79
+
make sure we're on the same page and interested in a feature.
80
+
81
+
The most common type of patch along these lines is a patch which adds new
82
+
configuration options. We consider additional configuration options to have
83
+
an exceptionally high lifetime support cost and are very unlikely to accept
84
+
them. Coordinate with us first.
85
+
86
+
**Not a Priority**: If you send us a patch against something which isn't a
87
+
priority, we probably won't have time to look at it. We don't give special
88
+
treatment to low-priority issues just because there's code written: we'd still
89
+
be spending time on something lower-priority when we could be spending it on
90
+
something higher-priority instead.
91
+
92
+
If you coordinate with us first, you can make sure your patch is in an area
93
+
of the codebase that we can prioritize.
94
+
95
+
**Overly Ambitious Patches**: Sometimes we'll get huge patches from new
96
+
contributors. These can have a lot of fundamental problems and require a huge
97
+
amount of our time to review and correct. If you're interested in contributing,
98
+
you'll have more success if you start small and learn as you go.
99
+
100
+
We can help you break a large change into smaller pieces and learn how the
101
+
codebase works as you proceed through the implementation, but only if you
102
+
coordinate with us first.
103
+
104
+
**Generality**: We often receive several feature requests which ask for similar
105
+
features, and can come up with a general approach which covers all of the use
106
+
cases. If you send us a patch for //your use case only//, the approach may be
107
+
too specific. When a cleaner and more general approach is available, we usually
108
+
prefer to pursue it.
109
+
110
+
By coordinating with us first, we can make you aware of similar use cases and
111
+
opportunities to generalize an approach. These changes are often small, but can
112
+
have a big impact on how useful a piece of code is.
113
+
114
+
**Infrastructure and Sequencing**: Sometimes patches are written against a piece
115
+
of infrastructure with major planned changes. We don't want to accept these
116
+
because they'll make the infrastructure changes more difficult to implement.
117
+
118
+
Coordinate with us first to make sure a change doesn't need to wait on other
119
+
pieces of infrastructure. We can help you identify technical blockers and
120
+
possibly guide you through resolving them if you're interested.
121
+
122
+
123
+
No Prototype Changes
124
+
====================
125
+
126
+
With rare exceptions, we do not accept patches for prototype applications for
127
+
the same reasons that we don't accept feature requests or bug reports. To learn
128
+
more about prototype applications, see
129
+
@{article:User Guide: Prototype Applications}.
130
+
131
+
132
+
You Must Sign the CLA
133
+
=====================
134
+
135
+
Before we can accept source code contributions, you need to submit a
136
+
[[ https://secure.phabricator.com/L28 | Contributor License Agreement ]]. Your
137
+
changes can not be accepted until you sign the agreement.
138
+
139
+
If you haven't signed it by the time you send changes for review, you'll be
140
+
reminded to sign it at that time.
141
+
142
+
If you're submitting work on behalf of a company (like your employer), the
143
+
company can sign the [[ https://secure.phabricator.com/L30 | Corporate
144
+
Contributor License Agreement ]] instead.
145
+
146
+
Both agreements are substantially similar to the Apache Foundation's CLAs. They
147
+
protect Phacility and users of Phabricator by making sure we have permission to
148
+
distribute your changes under an open source license.
149
+
150
+
151
+
No Pull Requests
152
+
================
153
+
154
+
We do not accept pull requests on GitHub:
155
+
156
+
- We can not monitor who has signed CLAs on GitHub. You must sign the CLA
157
+
to contribute, and we can't tell if you've signed it or not when you send
158
+
us a pull request.
159
+
- Pull requests do not get lint and unit tests run, so issues which are
160
+
normally caught statically can slip by.
161
+
- Phabricator is code review software, and developed using its own workflows.
162
+
Pull requests bypass some of these workflows (for example, they will not
163
+
trigger Herald rules to notify interested parties).
164
+
- GitHub is not the authoritative master repository and we maintain a linear
165
+
history, so merging pull requests is cumbersome on our end.
166
+
- If you're comfortable enough with Phabricator to contribute to it, you
167
+
should also be comfortable using it to submit changes.
168
+
169
+
Instead of sending a pull request, use `arc diff` to create a revision on the
170
+
upstream install. Your change will go through the normal Phabricator review
171
+
process.
172
+
173
+
(GitHub does not allow repositories to disable pull requests, which is why
174
+
it's technically possible to submit them.)
175
+
176
+
177
+
Alternatives
178
+
============
179
+
180
+
If you've written code but we're not accepting it into the upstream, some
181
+
alternative approaches include:
182
+
183
+
**Maintain a local fork.** This will require some ongoing effort to port your
184
+
changes forward when you update, but is often very reasonable for simple
185
+
changes.
186
+
187
+
**Develop as an application.** Many parts of Phabricator's infrastructure are
188
+
modular, and modularity is increasing over time. A lot of changes can be built
189
+
as external modules or applications without forking Phabricator itself. There
190
+
isn't much documentation or support for this right now, but you can look at
191
+
how other applications are implemented, and at other third-party code that
192
+
extends Phabricator.
193
+
194
+
**Rise to prominence.** We're more willing to accept borderline changes from
195
+
community members who are active, make multiple contributions, or have a history
196
+
with the project. This is not carte blanche, but distinguishing yourself can
197
+
make us feel more comfortable about supporting a change which is slightly
198
+
outside of our comfort zone.
199
+
200
+
201
+
Writing and Submitting Patches
202
+
==================
203
+
204
+
To actually submit a patch, run `arc diff` in `phabricator/`, `arcanist/`, or
205
+
`libphutil/`. When executed in these directories, `arc` should automatically
206
+
talk to the upstream install. You can add `epriestley` as a reviewer.
207
+
208
+
You should read the relevant coding convention documents before you submit a
209
+
change. If you're a new contributor, you don't need to worry about this too
210
+
much. Just try to make your code look similar to the code around it, and we
211
+
can help you through the details during review.
212
+
213
+
- @{article:General Coding Standards} (for all languages)
214
+
- @{article:PHP Coding Standards} (for PHP)
215
+
- @{article:Javascript Coding Standards} (for Javascript)
216
+
217
+
In general, if you're coordinating with us first, we can usually provide
218
+
guidance on how to implement things. The other articles in this section also
219
+
provide information on how to work in the Phabricator codebase.
220
+
221
+
Not Sure Where To Get Started?
222
+
==============================
223
+
224
+
If you don't have a specific bug or feature in mind and just want to write
225
+
some code, you can try to find something simple to get started with.
226
+
227
+
Because we're usually quick to fix easy bugs and issues, we often don't have a
228
+
very good backlog of starter tasks.
229
+
230
+
You can try searching in Maniphest for tasks tagged with #easy, which might
231
+
have something, but a lot of time this list is small and the tasks on it aren't
232
+
very fun or interesting even if they aren't technically too difficult.
233
+
234
+
In general, the best way to contribute is to come to us with a problem you
235
+
encountered or something you're interested in building, and then work with us
236
+
to find a solution to it or a plan to build it. We can help turn a hacky patch
237
+
into something that's upstreamable, and you'll get a fix or feature you want.
238
+
239
+
You can also look though the rest of the open tasks for something more
240
+
substantive that you're interested in. This will give you a better chance of
241
+
finding something that's relevant to you, but many tasks are large or blocked
242
+
by other large tasks.
243
+
244
+
If you do find something, feel free to leave a comment like "I'm interested in
245
+
working on this, is this something I could reasonably help with?". We're happy
246
+
to walk through things, break larger tasks down into more detail, provide
247
+
pointers to similar changes and the right places in the codebase to get started,
248
+
and generally figure out how to attack a problem.
249
+
250
+
251
+
Next Steps
252
+
==========
253
+
254
+
Continue by:
255
+
256
+
- returning to the @{article:Contributor Introduction}.
+189
src/docs/contributor/feature_requests.diviner
+189
src/docs/contributor/feature_requests.diviner
···
1
+
@title Contributing Feature Requests
2
+
@group detail
3
+
4
+
Describes how to file an effective Phabricator feature request.
5
+
6
+
Overview
7
+
========
8
+
9
+
Have a feature you'd like to see in Phabricator? This article describes how
10
+
to file an effective feature request.
11
+
12
+
The most important things to do are:
13
+
14
+
- understand the upstream;
15
+
- make sure your feature makes sense in the project;
16
+
- align your expectations around timelines and priorities;
17
+
- describe your problem, not your solution; and
18
+
- file a task in
19
+
[[ http://secure.phabricator.com/maniphest/task/create/ | Maniphest ]].
20
+
21
+
The rest of this article walks through these points in detail.
22
+
23
+
If you have a bug report (not a feature request), see
24
+
@{article:Contributing Bug Reports} for a more tailored guide.
25
+
26
+
For general information on contributing to Phabricator, see
27
+
@{article:Contributor Introduction}.
28
+
29
+
30
+
Understanding the Upstream
31
+
==========================
32
+
33
+
Before filing a feature request, it may be useful to understand how the
34
+
upstream operates.
35
+
36
+
The Phabricator upstream is [[ https://www.phacility.com | Phacility, Inc ]].
37
+
We maintain total control over the project and roadmap. There is no democratic
38
+
process, voting, or community-driven decision making. This model is better
39
+
at some things and worse at others than a more community-focused model would
40
+
be, but it is the model we operate under.
41
+
42
+
We have a cohesive vision for the project in the long term, and a general
43
+
roadmap that extends for years into the future. While the specifics of how
44
+
we get there are flexible, many major milestones are well-established.
45
+
46
+
Although we set project direction, the community is also a critical part of
47
+
Phabricator. We aren't all-knowing, and we rely on feedback to help us identify
48
+
issues, guide product direction, prioritize changes, and suggest features.
49
+
50
+
Feature requests are an important part of this, but we ultimately build only
51
+
features which make sense as part of the long term plan.
52
+
53
+
Since it's hard to absorb a detailed understanding of that vision, //describing
54
+
a problem// is often more effective than //requesting a feature//. We have the
55
+
context to develop solutions which fit into our plans, address similar use
56
+
cases, make sense with the available infrastructure, and work within the
57
+
boundaries of our product vision. For more details on this, see below.
58
+
59
+
60
+
Target Audiences
61
+
================
62
+
63
+
Some feature requests support very unusual use cases. Although we are broadly
64
+
inclusive of many different kinds of users and use cases, we are not trying
65
+
to make the software all things to all users. Use cases which are far afield
66
+
from the things the majority of users do with Phabricator often face substantial
67
+
barriers.
68
+
69
+
Phabricator is primarily targeted at software projects and organizations with
70
+
a heavy software focus. We are most likely to design, build, and prioritize
71
+
features which serve these organizations and projects.
72
+
73
+
Phabricator is primarily targeted at software professionals and other
74
+
professionals with adjacent responsibilities (like project management and
75
+
operations). Particularly, we assume users are proficient computer users and
76
+
familiar with software development concepts. We are most likely to design, build
77
+
and prioritize features which serve these users.
78
+
79
+
Phabricator is primarily targeted at professionals working in teams on full-time
80
+
projects. Particularly, we assume most users will use the software regularly and
81
+
are often willing to spend a little more time up front to get a more efficient
82
+
workflow in the long run. We are most likely to design, build and prioritize
83
+
features which serve these use cases.
84
+
85
+
Phabricator is not limited to these kinds of organizations, users and use cases,
86
+
but features which are aimed at a different group of users (like students,
87
+
casual projects, or inexperienced computer users) may be harder to get
88
+
upstreamed. Features aimed at very different groups of users (like wedding
89
+
planners, book clubs, or dogs) will be much harder to get upstreamed.
90
+
91
+
In many cases, a feature makes something better for all users. For example,
92
+
suppose we fixed an issue where colorblind users had difficulty doing something.
93
+
Dogs would benefit the most, but colorblind human users would also benefit, and
94
+
no one would be worse off. If the benefit for core users is very small these
95
+
kinds of features may be hard to prioritize, but there is no exceptional barrier
96
+
to getting them upstreamed.
97
+
98
+
In other cases, a feature makes something better for some users and worse for
99
+
other users. These kinds of features face a high barrier if they make the
100
+
software better at planning weddings and worse at reviewing code.
101
+
102
+
103
+
Setting Expectations
104
+
====================
105
+
106
+
We have a lot of users and a small team. Even if your feature is something we're
107
+
interested in and a good fit for where we want the product to go, it may take
108
+
us a long time to get around to building it.
109
+
110
+
We work full time on Phabricator, and our long-term roadmap has many years worth
111
+
of work. Your feature request is competing against thousands of other requests
112
+
for priority.
113
+
114
+
In general, we try to prioritize work that will have the greatest impact on the
115
+
most users. Many feature requests are perfectly reasonable requests, but have
116
+
very little impact, impact only a few users, and/or are complex to develop and
117
+
support relative to their impact. It can take us a long time to get to these.
118
+
119
+
Even if your feature request is simple and has substantial impact for a large
120
+
number of users, the size of the request queue means that it is mathematically
121
+
unlikely to be near the top.
122
+
123
+
You can find some information about how we prioritize in T4778. In particular,
124
+
we reprioritize frequently and can not accurately predict when we'll build a
125
+
feature which isn't very near to top of the queue.
126
+
127
+
As a whole, this means that the overwhelming majority of feature requests will
128
+
sit in queue for a long time without any updates, and that we won't be able to
129
+
give you any updates or predictions about timelines. One day, out of nowhere,
130
+
your feature will materialize. That day may be a decade from now. You should
131
+
have realistic expectations about this when filing a feature request.
132
+
133
+
If you want a concrete timeline, you can build the feature yourself. See
134
+
@{article:Contributing Code} for details and alternatives to working with the
135
+
upstream.
136
+
137
+
138
+
Describe Problems
139
+
=================
140
+
141
+
When you file a feature request, it is really helpful to describe the problem
142
+
you're facing first, not just your desired solution.
143
+
144
+
Often, your problem may have a lot in common with other similar problems. If we
145
+
understand your use case we can compare it to other use cases and sometimes find
146
+
a more powerful or more general solution which solves several problems at once.
147
+
148
+
At other times, we'll have a planned solution to the problem that might be
149
+
different from your desired solution but accomplish the same goal. Understanding
150
+
the root issue can let us merge and contextualize things.
151
+
152
+
Sometimes there's already a way to solve your problem that might just not be
153
+
obvious.
154
+
155
+
Finally, your proposed solution may not be compatible with the direction we
156
+
want to take the product, but we may be able to come up with another solution
157
+
which has approximately the same effect and does fit into the product direction.
158
+
159
+
If you only describe the solution and not the problem, we can't generalize,
160
+
contextualize, merge, reframe, or offer alternative solutions or workarounds.
161
+
162
+
163
+
Create a Task in Maniphest
164
+
==========================
165
+
166
+
If you think your feature might be a good fit for the upstream, have reasonable
167
+
expectations about it, and have a good description of the problem you're trying
168
+
to solve, you're ready to file a feature request:
169
+
170
+
https://secure.phabricator.com/maniphest/task/create/
171
+
172
+
You can file feature requests in places other than Maniphest (like GitHub), but
173
+
we can address them far more effectively if you file them in the upstream.
174
+
Feature requests filed elsewhere will generally be moved to the upstream.
175
+
176
+
If you have a quick question or want to discuss something before filing a
177
+
request, IRC is a great way to get a quick answer. You can find information
178
+
about IRC and other support channels in @{article: Give Feedback! Get Support!}.
179
+
180
+
181
+
Next Steps
182
+
==========
183
+
184
+
Continue by:
185
+
186
+
- learning about @{article: Contributing Bug Reports}; or
187
+
- reading general support information in
188
+
@{article: Give Feedback! Get Support!}; or
189
+
- returning to the @{article:Contributor Introduction}.