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
   7 Level Requirements
   8 ==================
   9
  10 We accept feature requests through two channels: paid support and community
  11 support.
  12
  13 If you are a paying customer, use the
  14 [[ https://admin.phacility.com/u/support | Support Channel ]] for your account
  15 to request features. This document may help you frame your requests in a way
  16 that lets us address them more quickly, but you do not need to read it or
  17 follow the guidelines.
  18
  19 Other users can file requests on the
  20 [[ https://phurl.io/u/discourse | community forum ]].
  21
  22
  23 Overview
  24 ========
  25
  26 This article describes how to file an effective feature request.
  27
  28 The most important things to do are:
  29
  30   - understand the upstream;
  31   - make sure your feature makes sense in the project;
  32   - align your expectations around timelines and priorities;
  33   - describe your problem, not your solution.
  34
  35 The rest of this article walks through these points in detail.
  36
  37 If you have a bug report (not a feature request), see
  38 @{article:Contributing Bug Reports} for a more tailored guide.
  39
  40 For general information on contributing to Phabricator, see
  41 @{article:Contributor Introduction}.
  42
  43
  44 Understanding the Upstream
  45 ==========================
  46
  47 Before filing a feature request, it may be useful to understand how the
  48 upstream operates.
  49
  50 The Phabricator upstream is [[ https://www.phacility.com | Phacility, Inc ]].
  51 We maintain total control over the project and roadmap. There is no democratic
  52 process, voting, or community-driven decision making. This model is better
  53 at some things and worse at others than a more community-focused model would
  54 be, but it is the model we operate under.
  55
  56 We have a cohesive vision for the project in the long term, and a general
  57 roadmap that extends for years into the future. While the specifics of how
  58 we get there are flexible, many major milestones are well-established.
  59
  60 Although we set project direction, the community is also a critical part of
  61 Phabricator. We aren't all-knowing, and we rely on feedback to help us identify
  62 issues, guide product direction, prioritize changes, and suggest features.
  63
  64 Feature requests are an important part of this, but we ultimately build only
  65 features which make sense as part of the long term plan.
  66
  67 Since it's hard to absorb a detailed understanding of that vision, //describing
  68 a problem// is often more effective than //requesting a feature//. We have the
  69 context to develop solutions which fit into our plans, address similar use
  70 cases, make sense with the available infrastructure, and work within the
  71 boundaries of our product vision. For more details on this, see below.
  72
  73
  74 Target Audiences
  75 ================
  76
  77 Some feature requests support very unusual use cases. Although we are broadly
  78 inclusive of many different kinds of users and use cases, we are not trying
  79 to make the software all things to all users. Use cases which are far afield
  80 from the things the majority of users do with Phabricator often face substantial
  81 barriers.
  82
  83 Phabricator is primarily targeted at software projects and organizations with
  84 a heavy software focus. We are most likely to design, build, and prioritize
  85 features which serve these organizations and projects.
  86
  87 Phabricator is primarily targeted at software professionals and other
  88 professionals with adjacent responsibilities (like project management and
  89 operations). Particularly, we assume users are proficient computer users and
  90 familiar with software development concepts. We are most likely to design, build
  91 and prioritize features which serve these users.
  92
  93 Phabricator is primarily targeted at professionals working in teams on full-time
  94 projects. Particularly, we assume most users will use the software regularly and
  95 are often willing to spend a little more time up front to get a more efficient
  96 workflow in the long run. We are most likely to design, build and prioritize
  97 features which serve these use cases.
  98
  99 Phabricator is not limited to these kinds of organizations, users and use cases,
 100 but features which are aimed at a different group of users (like students,
 101 casual projects, or inexperienced computer users) may be harder to get
 102 upstreamed. Features aimed at very different groups of users (like wedding
 103 planners, book clubs, or dogs) will be much harder to get upstreamed.
 104
 105 In many cases, a feature makes something better for all users. For example,
 106 suppose we fixed an issue where colorblind users had difficulty doing something.
 107 Dogs would benefit the most, but colorblind human users would also benefit, and
 108 no one would be worse off. If the benefit for core users is very small these
 109 kinds of features may be hard to prioritize, but there is no exceptional barrier
 110 to getting them upstreamed.
 111
 112 In other cases, a feature makes something better for some users and worse for
 113 other users. These kinds of features face a high barrier if they make the
 114 software better at planning weddings and worse at reviewing code.
 115
 116
 117 Setting Expectations
 118 ====================
 119
 120 We have a lot of users and a small team. Even if your feature is something we're
 121 interested in and a good fit for where we want the product to go, it may take
 122 us a long time to get around to building it.
 123
 124 We work full time on Phabricator, and our long-term roadmap (which we call our
 125 [[ https://secure.phabricator.com/w/starmap/ | Starmap ]]) has many years worth
 126 of work. Your feature request is competing against thousands of other requests
 127 for priority.
 128
 129 In general, we try to prioritize work that will have the greatest impact on the
 130 most users. Many feature requests are perfectly reasonable requests, but have
 131 very little impact, impact only a few users, and/or are complex to develop and
 132 support relative to their impact. It can take us a long time to get to these.
 133
 134 Even if your feature request is simple and has substantial impact for a large
 135 number of users, the size of the request queue means that it is mathematically
 136 unlikely to be near the top.
 137
 138 You can find some information about how we prioritize in
 139 [[ https://secure.phabricator.com/w/planning/ | Planning ]]. In particular,
 140 we reprioritize frequently and can not accurately predict when we'll build a
 141 feature which isn't very near to top of the queue.
 142
 143 As a whole, this means that the overwhelming majority of feature requests will
 144 sit in queue for a long time without any updates, and that we won't be able to
 145 give you any updates or predictions about timelines. One day, out of nowhere,
 146 your feature will materialize. That day may be a decade from now. You should
 147 have realistic expectations about this when filing a feature request.
 148
 149
 150 Describe Problems
 151 =================
 152
 153 When you file a feature request, we need you to describe the problem you're
 154 facing first, not just your desired solution. Describing the problem you are
 155 facing is the **most important part** of a feature request.
 156
 157 Often, your problem may have a lot in common with other similar problems. If we
 158 understand your use case we can compare it to other use cases and sometimes find
 159 a more powerful or more general solution which solves several problems at once.
 160
 161 At other times, we'll have a planned solution to the problem that might be
 162 different from your desired solution but accomplish the same goal. Understanding
 163 the root issue can let us merge and contextualize things.
 164
 165 Sometimes there's already a way to solve your problem that might just not be
 166 obvious.
 167
 168 Finally, your proposed solution may not be compatible with the direction we
 169 want to take the product, but we may be able to come up with another solution
 170 which has approximately the same effect and does fit into the product direction.
 171
 172 If you only describe the solution and not the problem, we can't generalize,
 173 contextualize, merge, reframe, or offer alternative solutions or workarounds.
 174
 175 You must describe the problem you are facing when filing a feature request. We
 176 will not accept feature requests which do not contextualize the request by
 177 describing the root problem.
 178
 179 If you aren't sure exactly what we're after when we ask you to describe a root
 180 problem, you can find examples and more discussion in
 181 @{article:Describing Root Problems}.
 182
 183
 184 Hypotheticals
 185 =============
 186
 187 We sometimes receive hypothetical feature requests about anticipated problems
 188 or concerns which haven't actually occurred yet. We usually can't do much about
 189 these until the problems actually occur, since the context required to
 190 understand and properly fix the root issue won't exist.
 191
 192 One situation where this happens is when installs are thinking about adopting
 193 Phabricator and trying to guess what problems users might encounter during the
 194 transition. More generally, this includes any request like "if users do **X**,
 195 they might find **Y** confusing", where no actual users have encountered
 196 confusion yet.
 197
 198 These requests are necessarily missing important context, maybe including the
 199 answers to questions like these:
 200
 201   - Why did users do **X**?
 202   - What were they trying to do?
 203   - What did they expect to happen?
 204   - How often do users do this?
 205
 206 The answers to these questions are important in establishing that the issue is
 207 really a problem, figuring out the best solution for it, and prioritizing the
 208 issue relative to other issues.
 209
 210 Without knowing this information, we can't be confident that we've found a good
 211 solution to the problem, can't know if we've actually fixed the problem, and
 212 can't even know if the issue was really a problem in the first place (some
 213 hypothetical requests describe problems which no users ever encounter).
 214
 215 We usually can't move forward without this information. In particular, we don't
 216 want to spend time solving hypothetical problems which no real users will ever
 217 encounter: the value of those changes is zero (or negative, by making the
 218 product more complex without providing a benefit), but they consume development
 219 time which could be better spent building much more valuable features.
 220
 221 Generally, you should wait until a problem actually occurs before filing a
 222 request about it.
 223
 224
 225 Next Steps
 226 ==========
 227
 228 Continue by:
 229
 230   - learning about @{article: Contributing Bug Reports}; or
 231   - reading general support information in @{article:Support Resources}; or
 232   - returning to the @{article:Contributor Introduction}.