[Summary view] [Print] [Text view]

   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}.