Differential D10764 Diff 25838 src/docs/contributor/feature_requests.diviner

Changeset View

Standalone View

src/docs/contributor/feature_requests.diviner

This file was added.

				@title Contributing Feature Requests
				@group contrib

				Describes how to file an effective Phabricator feature request.

				Overview
				========

				Have a feature you'd like to see in Phabricator? This article describes how
				to file an effective feature request.

				The most important things to do are:

				- understand the upstream;
				- make sure your feature makes sense in the project;
				- align your expectations around timelines and priorities;
				- describe your problem, not your solution; and
				- file a task in
				[[ http://secure.phabricator.com/maniphest/task/create/ \| Maniphest ]].

				The rest of this article walks through these points in detail.

				If you have a bug report (not a feature request), see
				@{article:Contributing Bug Reports} for a more tailored guide.

				For general information on contributing to Phabricator, see
				@{article:Contributor Introduction}.


				Understanding the Upstream
				==========================

				Before filing a feature request, it may be useful to understand how the
				upstream operates.

				The Phabricator upstream is [[ https://www.phacility.com \| Phacility, Inc ]].
				We maintain total control over the project and roadmap. There is no democratic
				process, voting, or community-driven decision making. This model is better
				at some things and worse at some things than a more community-focused model, but
				the reality of the project is that we rule it with an iron fist.
				chadUnsubmitted Not Done Inline Actions I like iron fist, but might come off harsh? chad: I like iron fist, but might come off harsh?
				btrahanUnsubmitted Not Done Inline Actions "We acknowledge this model is better at some things and worse at some things than a more community-focused model." (I think we're good here without adding more?) btrahan: "We acknowledge this model is better at some things and worse at some things than a more…

				We have cohesive, long-term plans for the project and a focused vision on how
				the product should work. We have a //relatively// clear idea of what the product
				will look like over the next several years. This vision is flexible and dynamic,
				but major pieces of it are well established.

				Although we set project direction, the community is also a critical part of
				Phabricator. We aren't all-knowing, and we rely on feedback to help us identify
				issues, guide product direction, prioritize changes, and suggest features.

				Feature requests are an important part of this, but we ultimately build only
				features which make sense as part of the long term plan.

				Since it's hard to absorb a detailed understanding of that vision, //describing
				a problem// is often more effective than //requesting a feature//. We have the
				context to develop solutions which fit into our plans, address similar use
				cases, make sense with the available infrastructure, and work within the
				boundaries of our product vision. For more details on this, see below.


				Target Audiences
				================

				Some feature requests support very unusual use cases. Although we are broadly
				inclusive of many different kinds of users and use cases, we are not trying
				to make the software all things to all users. Use cases which are far afield
				from the things the majority of users do with Phabricator often face substantial
				barriers.

				Phabricator is primarily targeted at software projects and organizations with
				a heavy software focus. We are most likely to design, build, and prioritize
				features which serve these organizations and projects.

				Phabricator is primarily targeted at software professionals and other
				professionals with adjacent responsibilities (like project management and
				operations). Particularly, we assume users are proficient computer users and
				familiar with software development concepts. We are most likely to design, build
				and prioritize features which serve these users.

				Phabricator is primarily targeted at professionals working in teams on full-time
				projects. Particularly, we assume most users will use the software regularly and
				are often willing to spend a little more time up front to get a more efficient
				workflow in the long run. We are most likely to design, build and prioritize
				features which serve these use cases.

				Phabricator is not limited to these kinds of organizations, users and use cases,
				but features which are aimed at a different group of users (like students,
				casual projects, or inexperienced computer users) may be harder to get
				upstreamed. Features aimed at very different groups of users (like wedding
				planners, book clubs, or dogs) will be much harder to get upstreamed.

				In many cases, a feature makes something better for all users. For example,
				suppose we fixed an issue where colorblind users had difficulty doing something.
				Dogs would benefit the most, but colorblind human users would also benefit, and
				no one would be worse off. If the benefit for core users is very small these
				kinds of features may be hard to prioritize, but there is no exceptional barrier
				to getting them upstreamed.

				In other cases, a feature makes something better for some users and worse for
				other users. These kinds of features face a high barrier if they make the
				software better at planning weddings and worse at reviewing code.


				Setting Expectations
				====================

				We have a lot of users and a small team. Even if your feature is something we're
				interested in and a good fit for where we want the product to go, it may take
				us a long time to get around to building it.

				We work full time on Phabricator, and our long-term roadmap has many years worth
				of work. Your feature request is competing against thousands of other requests
				for priority.

				In general, we try to prioritize work that will have the greatest impact on the
				most users. Many feature requests are perfectly reasonable requests, but have
				very little impact, impact only a few users, and/or are complex to develop and
				support relative to their impact. It can take us a long time to get to these.

				Even if your feature request is simple and has substantial impact for a large
				number of users, the size of the request queue means that it is mathematically
				unlikely to be near the top.

				You can find some information about how we prioritize in T4778. In particular,
				btrahanUnsubmitted Not Done Inline Actions link T4778 btrahan: link T4778
				we reprioritize frequently and can not accurately predict when we'll build a
				feature which isn't very near to top of the queue.

				As a whole, this means that the overwhelming majority of feature requests will
				sit in queue for a long time without any updates, and that we won't be able to
				give you any updates or predictions about timelines. One day, out of nowhere,
				your feature will materialize. That day may be a decade from now. You should
				have realistic expectations about this when filing a feature request.

				If you want a concrete timeline, you can build the feature yourself. See
				@{article:Contributing Code} for details and alternatives to working with the
				upstream.


				Describe Problems
				=================

				When you file a feature request, it is really helpful to describe the problem
				you're facing first, not just your desired solution.

				Often, your problem may have a lot in common with other similar problems. If we
				understand your use case we can compare it to other use cases and sometimes find
				a more powerful or more general solution which solves several problems at once.

				At other times, we'll have a planned solution to the problem that might be
				different from your desired solution but accomplish the same goal. Understanding
				the root issue can let us merge and contextualize things.

				Sometimes there's already a way to solve your problem that might just not be
				obvious.

				Finally, your proposed solution may not be compatible with the direction we
				want to take the product, but we may be able to come up with another solution
				which has approximately the same effect and does fit into the product direction.

				If you only describe the solution and not the problem, we can't generalize,
				contextualize, merge, reframe, or offer alternative solutions or workarounds.


				Create a Task in Maniphest
				==========================

				If you think your feature might be a good fit for the upstream, have reasonable
				expectations about it, and have a good description of the problem you're trying
				to solve, you're ready to file a feature request:

				https://secure.phabricator.com/maniphest/task/create/

				You can file feature requests in places other than Maniphest (like GitHub), but
				we can address them far more effectively if you file them in the upstream.
				Feature requests filed elsewhere will generally be moved to the upstream.

				If you have a quick question or want to discuss something before filing a
				request, IRC is a great way to get a quick answer. You can find information
				about IRC and other support channels in @{article: Give Feedback! Get Support!}.


				Next Steps
				==========

				Continue by:

				- learning about @{article: Contributing Bug Reports}; or
				- reading general support information in
				@{article: Give Feedback! Get Support!}; or
				- returning to the @{article:Contributor Introduction}.