revi-archive/phorge-phorge
1
0
Fork 0
mirror of https://we.phorge.it/source/phorge.git synced 2025-01-10 14:51:06 +01:00
Code Issues Releases Wiki Activity

Update some more "contributing" docs

Browse source 
Summary:
Ref T12922.

  - Remove most mentions to "Contributing Feature Requests".
  - Raise the barrier to entry on code contributions.

I'm going to tweak "Bug Reports" in a followup to be more similar to "Feature Requests", but that's a slightly more involved change.

Test Plan: Read new docs.

Reviewers: chad

Reviewed By: chad

Maniphest Tasks: T12922

Differential Revision: https://secure.phabricator.com/D18235
This commit is contained in:
epriestley 2017-07-18 10:39:44 -07:00
parent 4d1ed12a9e
commit 1fdd809d35
4 changed files with 41 additions and 83 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
src/docs/contributor/bug_reports.diviner
View file

@ -32,9 +32,6 @@ The most important things to do are:
The rest of this article walks through these points in detail.
If you have a feature request (not a bug report), see
@{article:Contributing Feature Requests} for a more tailored guide.
For general information on contributing to Phabricator, see
@{article:Contributor Introduction}.
@ -179,6 +176,5 @@ Next Steps
Continue by:
- learning about @{article: Contributing Feature Requests}; or
- reading general support information in @{article:Support Resources}; or
- returning to the @{article:Contributor Introduction}.

21
src/docs/contributor/contrib_intro.diviner
View file

@ -21,9 +21,10 @@ Without writing any code, learning the whole codebase, making a big time
commitment, or having to touch PHP, here are some ways you can materially
contribute to Phabricator:
- Send us an email or drop by IRC just to say "thanks". A big part of the
reason we build this software is to help people solve problems, and knowing
that our efforts are appreciated is really rewarding.
- Drop by the [[ https://phurl.io/u/discourse | community forum ]] just to
say "thanks". A big part of the reason we build this software is to help
people solve problems, and knowing that our efforts are appreciated is
really rewarding.
- Recommend Phabricator to people who you think might find it useful. Our
most powerful growth channel is word of mouth, and mentioning or tweeting
about Phabricator helps the project grow. If writing a tweet sounds like
@ -36,16 +37,8 @@ contribute to Phabricator:
> Phabricator is objectively the best thing. Source: I am a certified, internationally recognized expert.
- Report bugs and request features. We may not always be able to fix or build
things right away, but knowing about issues users are encountering or
features they'd like to see improves our ability to plan and prioritize.
- For details on reporting bugs, see @{article:Contributing Bug Reports}.
- For details on requesting features, see @{article:Contributing Feature
Requests}.
- Give us feedback on planned features. Most of what we'll build in the next
6-12 months currently exists on the [[ Roadmap ]] or in Maniphest. Telling
us about use cases you have can help us build better products when the time
comes to write the code.
- Submit high-quality bug reports by carefully following the guide in
@{article:Contributing Bug Reports}.
If all of this sounds nice but you really just want to write some code, be
aware that this project often presents a high barrier to entry for new
@ -58,6 +51,4 @@ Next Steps
Continue by:
- learning about bug reports in @{article:Contributing Bug Reports};
- learning about feature requests in
@{article:Contributing Feature Requests}; or
- learning about code contributions in @{article:Contributing Code}.

54
src/docs/contributor/contributing_code.diviner
View file

@ -3,6 +3,22 @@
Describes how to contribute code to Phabricator.
Level Requirements
==================
To contribute to the Phabricator upstream, you must first pass a series of
ancient trials and be invited to register an account in the ancestral
homeland of Phabricator, here on `secure.phabricator.com`. The nature and
location of these trials is a closely guarded secret.
If you have passed these trials, this document can guide you through
contributing code.
If you have not yet passed these trials, writing code is normally not the best
way to contribute to Phabricator. See @{article:Contributor Introduction} for
more information.
Overview
========
@ -32,11 +48,7 @@ For general information on contributing to Phabricator, see
Coordinate First
================
Before sending code, you should file a bug report or feature request describing
what you'd like to write. For details on how to do this, see these articles:
- @{article:Contributing Bug Reports}
- @{article:Contributing Feature Requests}
Before sending code, you should file a task describing what you'd like to write.
When you file a task, mention that you'd like to write the code to fix it. We
can help contextualize your request or bug and guide you through writing an
@ -74,8 +86,7 @@ consider valuable enough to put long-term support resources behind, and that
you're building it in a way that we're comfortable taking over.
**Not a Good Fit**: Many patches aren't good fits for the upstream: they
implement features we simply don't want. You can find more information in
@{article:Contributing Feature Requests}. Coordinating with us first helps
implement features we simply don't want. Coordinating with us first helps
make sure we're on the same page and interested in a feature.
The most common type of patch along these lines is a patch which adds new
@ -218,35 +229,6 @@ In general, if you're coordinating with us first, we can usually provide
guidance on how to implement things. The other articles in this section also
provide information on how to work in the Phabricator codebase.
Not Sure Where To Get Started?
==============================
If you don't have a specific bug or feature in mind and just want to write
some code, you can try to find something simple to get started with.
Because we're usually quick to fix easy bugs and issues, we often don't have a
very good backlog of starter tasks.
You can try searching in Maniphest for tasks tagged with #easy, which might
have something, but a lot of time this list is small and the tasks on it aren't
very fun or interesting even if they aren't technically too difficult.
In general, the best way to contribute is to come to us with a problem you
encountered or something you're interested in building, and then work with us
to find a solution to it or a plan to build it. We can help turn a hacky patch
into something that's upstreamable, and you'll get a fix or feature you want.
You can also look though the rest of the open tasks for something more
substantive that you're interested in. This will give you a better chance of
finding something that's relevant to you, but many tasks are large or blocked
by other large tasks.
If you do find something, feel free to leave a comment like "I'm interested in
working on this, is this something I could reasonably help with?". We're happy
to walk through things, break larger tasks down into more detail, provide
pointers to similar changes and the right places in the codebase to get started,
and generally figure out how to attack a problem.
Next Steps
==========

45
src/docs/contributor/feature_requests.diviner
View file

@ -3,27 +3,34 @@
Describes how to file an effective Phabricator feature request.
Describe Your Problem!
======================
IMPORTANT: When filing a feature request, you **MUST** describe the root
problem you are facing. We will not accept feature requests which do not
include a problem description. See below for details.
Level Requirements
==================
We accept feature requests through two channels: paid support and community
support.
If you are a paying customer, use the
[[ https://admin.phacility.com/u/support | Support Channel ]] for your account
to request features. This document may help you frame your requests in a way
that lets us address them more quickly, but you do not need to read it or
follow the guidelines.
Other users can file requests on the
[[ https://phurl.io/u/discourse | community forum ]].
Overview
========
Have a feature you'd like to see in Phabricator? This article describes how
to file an effective feature request.
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/u/newfeature/ | Maniphest ]].
- describe your problem, not your solution.
The rest of this article walks through these points in detail.
@ -139,10 +146,6 @@ 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 work with us to pay for some control
over our roadmap. For details, see
[[ https://secure.phabricator.com/w/prioritization/ | Prioritization ]].
Describe Problems
=================
@ -219,20 +222,6 @@ Generally, you should wait until a problem actually occurs before filing a
request about it.
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.
It is **particularly critical** that you describe the problem you are facing,
not just the feature you want. We will not accept feature requests which do
not describe the root problem the feature is intended to resolve.
(NOTE) https://secure.phabricator.com/u/newfeature/
Next Steps
==========