revi-archive/phorge-phorge
1
0
Fork 0
mirror of https://we.phorge.it/source/phorge.git synced 2024-11-10 00:42:41 +01:00
Code Issues Releases Wiki Activity

Update support documentation for modern times

Browse source 
Summary:
Basically similar to D13941 but a little more extreme:

  - Really strongly emphasize reproducibility for bug reports, and set users up for rejection if they don't satisfy this.
  - Really strongly emphasize problem descriptions for feature requests, and set users up for rejection.
  - Get rid of various "please give us feedback"; we get plenty of feedback these days.
  - Some modernization tweaks.
  - Split the support document into:
    - Stuff we actually support for free (security / good bug reports / feature requests).
    - Stuff you can pay us for (hosting / consulting / prioritization).
    - A nebulous "community" section, with appropriate (low) expectations that better reflects reality.

My overall goals here are:

  - Set expectations better, so users don't show up in IRC expecting it to be a "great place to get amazing support" or whatever the docs said in 2011.
  - Possibly move the needle slightly on bug reports / feature request quality, maybe.

Test Plan: Read changes carefully.

Reviewers: chad

Reviewed By: chad

Differential Revision: https://secure.phabricator.com/D14305
This commit is contained in:
epriestley 2015-10-19 13:29:24 -07:00
parent fbd365d571
commit 4cb2ec1120
7 changed files with 193 additions and 91 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
src/docs/book/user.book
View file

@ -31,6 +31,9 @@
},
"fieldmanual": {
"name": "Field Manuals"
},
"cellar": {
"name": "Musty Cellar"
}
}
}

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

@ -3,6 +3,14 @@
Describes how to file an effective Phabricator bug report.
Include Reproduction Steps!
===========================
IMPORTANT: When filing a bug report, you **MUST** include reproduction
instructions. We can not help fix bugs we can not reproduce, and will not
accept reports which omit reproduction instructions. See below for details.
Overview
========
@ -28,6 +36,7 @@ If you have a feature request (not a bug report), see
For general information on contributing to Phabricator, see
@{article:Contributor Introduction}.
Common Fixes
============
@ -73,6 +82,9 @@ Supported Issues
Before filing a bug, make sure you're filing an issue against something we
support.
**We can NOT help you with issues we can not reproduce.** It is critical that
you explain how to reproduce the issue when filing a report.
**We do NOT support prototype applications.** If you're running into an issue
with a prototype application, you're on your own. For more information about
prototype applications, see @{article:User Guide: Prototype Applications}.
@ -101,6 +113,7 @@ Otherwise, if you're having an issue with a supported first-party application
and followed the upstream install instructions on a normal computer, we're happy
to try to help.
Getting More Information
========================
@ -121,6 +134,7 @@ help us figure out and resolve an issue.
troubleshooting. Adjusting settings or enabling debugging modes may give
you more information about the issue.
Reproducibility
===============
@ -135,7 +149,9 @@ trouble narrowing something down or want to check if updating might fix an
issue.
It is nearly impossible for us to resolve many issues if we can not reproduce
them.
them. We will not accept reports which do not contain the information required
to reproduce problems.
Unreproducible Problems
=======================
@ -161,6 +177,7 @@ We will make a reasonable effort to reproduce problems, but can not help with
issues which we can't reproduce. You can make sure we're able to help resolve
your issue by generating clear reproduction steps.
Create a Task in Maniphest
==========================
@ -168,11 +185,10 @@ If you're up to date, supported, have collected information about the problem,
and have the best reproduction instructions you can come up with, you're ready
to file an issue.
We'll look at any issue report we can find (we monitor IRC, email,
StackOverflow, Quora, Facebook and Twitter), but the upstream Maniphest is the
authoritative bug tracker and the best place to file:
It is **particularly critical** that you include reproduction steps. We will
not accept reports which describe issues we can not reproduce.
https://secure.phabricator.com/maniphest/task/create/
(NOTE) https://secure.phabricator.com/maniphest/task/create/
If you don't want to file there (or, for example, your bug relates to being
unable to log in or unable to file an issue in Maniphest) you can file on any
@ -182,12 +198,9 @@ filed against the upstream than if they're filed somewhere else.
| Effectiveness | Filing Method |
|---|---|
| Best | Upstream Maniphest |
| Ehhh | Quora, StackOverflow, Facebook, email, etc. |
| Ehhh | Quora, StackOverflow, Facebook, Jelly, email, etc. |
| What | Passive-aggressive tweet |
If you have a quick question or want to discuss something before filing an
issue, IRC is a great way to get a sanity check first. You can find information
about IRC in @{article: Give Feedback! Get Support!}.
Next Steps
==========
@ -195,6 +208,5 @@ Next Steps
Continue by:
- learning about @{article: Contributing Feature Requests}; or
- reading general support information in
@{article: Give Feedback! Get Support!}; or
- reading general support information in @{article:Support Resources}; or
- returning to the @{article:Contributor Introduction}.

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

@ -23,8 +23,7 @@ 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. You can find ways to
get in touch in @{article:Give Feedback! Get Support!}
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
@ -40,7 +39,6 @@ contribute to Phabricator:
- 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 ways to do this, see @{article:Give Feedback! Get Support!}
- For details on reporting bugs, see @{article:Contributing Bug Reports}.
- For details on requesting features, see @{article:Contributing Feature
Requests}.
@ -48,16 +46,11 @@ contribute to Phabricator:
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.
- Hang out in IRC, and maybe answer a question or two. IRC is a completely
legit place for serious hackers to hang out anyway, but while you're there
you might see someone ask a question that you know the answer to. Helping
them out (or pointing them to the right documentation) is a big help to us.
You can find details about the IRC channel in
@{article:Give Feedback! Get Support!}
If all of this sounds nice but you really just want to write some code, that's
awesome too. To get started with contributing code, see
@{article:Contributing Code}.
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
contributors. To continue, see @{article:Contributing Code}.
Next Steps
==========
@ -65,6 +58,6 @@ Next Steps
Continue by:
- learning about bug reports in @{article:Contributing Bug Reports};
- learning about feature requests in @{article:Contributing Feature Requests};
- learning about code contributions in @{article:Contributing Code}; or
- getting in touch with @{article:Give Feedback! Get Support!}
- learning about feature requests in
@{article:Contributing Feature Requests}; or
- learning about code contributions in @{article:Contributing Code}.

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

@ -3,6 +3,13 @@
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.
Overview
========
@ -138,8 +145,9 @@ 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.
When you file a feature request, we need you to describe the problem you're
facing first, not just your desired solution. Describing the problem you are
facing is the **most important part** of a feature request.
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
@ -159,6 +167,10 @@ 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.
You must describe the problem you are facing when filing a feature request. We
will not accept feature requests which do not contextualize the request by
describing the root problem.
Hypotheticals
=============
@ -206,13 +218,13 @@ 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:
to solve, you're ready to file a feature request.
https://secure.phabricator.com/maniphest/task/create/
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.
If you have a quick question or want to discuss something before filing a
request, IRC is the best way to get a quick answer. You can find information
about IRC and other support channels in @{article: Give Feedback! Get Support!}.
(NOTE) https://secure.phabricator.com/maniphest/task/create/
Next Steps
@ -221,6 +233,5 @@ Next Steps
Continue by:
- learning about @{article: Contributing Bug Reports}; or
- reading general support information in
@{article: Give Feedback! Get Support!}; or
- reading general support information in @{article:Support Resources}; or
- returning to the @{article:Contributor Introduction}.

43
src/docs/user/feedback.diviner
View file

@ -1,44 +1,7 @@
@title Give Feedback! Get Support!
@short Feedback/Support
@group intro
@group cellar
How to give us feedback, report bugs, and request features, and get support for
problems with Phabricator.
Deprecated.
Overview
========
We'd love to hear your feedback about Phabricator, whether it's good or bad. The
best ways to provide feedback and get support are:
- For bug reports and feature requests, file a task in our task tracker,
Maniphest.
- For questions and real-time chat, join the IRC channel.
- If you just want to provide some quick feedback, you can tweet at
us ([[ http://twitter.com/phabricator | @phabricator ]]).
Bugs and Requests
=====================
The best way to report bugs and request features is through
[[http://secure.phabricator.com/maniphest/task/create/ | Maniphest]]. For
information on filing good bug reports and feature requests, see:
- @{article:Contributing Bug Reports}
- @{article:Contributing Feature Requests}
IRC
==========
We're active in `#phabricator` on FreeNode, and it's the best place to ask
questions and get support.
Next Steps
==========
Continue by:
- learning more about bug reports with @{article:Contributing Bug Reports}; or
- learning more about feature requests with
@{article:Contributing Feature Requests}; or
- contributing to Phabricator with @{article:Contributor Introduction}.
This article has moved to @{article:Support Resources}.

27
src/docs/user/reporting_security.diviner
View file

@ -3,7 +3,8 @@
Describes how to report security vulnerabilities in Phabricator.
= Overview =
Overview
========
Phabricator runs a disclosure and award program through
[[ https://www.hackerone.com/ | HackerOne ]]. This program is the best way to
@ -19,23 +20,17 @@ how to participate.
We have a 24 hour response timeline, and are usually able to respond to (and,
very often, fix) issues more quickly than that.
= Other Channels =
You can also contact us on another channel if you prefer. See
@{article:Give Feedback! Get Support!} for a list of ways to get in touch
with us.
Other Channels
==============
= Getting Notified =
If you aren't sure if something qualifies or don't want to report via
HackerOne, you can submit the issue as a normal bug report. For instructions,
see @{article:Contributing Bug Reports}.
When we fix significant security vulnerabilities, we currently publish
information:
- on our [[ https://www.facebook.com/phabricator | Facebook Page ]];
- on our [[ https://twitter.com/phabricator | Twitter Feed ]];
- and on IRC (`#phabricator` on FreeNode).
Get Updated
===========
If you'd prefer to receive information on other channels, let us know.
General information about security is reported monthly in the
[[ http://phabricator.org/changelog/ | Changelog ]]. This includes low impact
issues, reports we did not act on, and other details.
General information about security changes is reported weekly in the
[[ https://secure.phabricator.com/w/changelog/ | Changelog ]].

125
src/docs/user/support.diviner Normal file
View file

@ -0,0 +1,125 @@
@title Support Resources
@short Support
@group intro
Resources for reporting bugs, requesting features, and getting support.
Overview
========
This document describes available support resources.
The upstream provides active, free support for a narrow range of problems
(primarily, security issues and reproducible bugs).
The upstream does not provide free support for general problems with installing
or configuring Phabricator. You may be able to get some help with these
kinds of issues from the community.
Reporting Security Vulnerabilities
==================================
The upstream accepts, fixes, and awards bounties for reports of material
security issues with the software.
To report security issues, see @{article:Reporting Security Vulnerabilities}.
Reporting Bugs
==============
The upstream will accept **reproducible** bug reports in modern, first-party
production code running in reasonable environments.
To report bugs, see @{article:Contributing Bug Reports}.
Requesting Features
===================
The upstream accepts feature requests which **describe problems** you would
like Phabricator to be able to solve.
To request features, see @{article:Contributing Feature Requests}.
Contributing
============
Phabricator is a very difficult project to contribute to. New contributors
will face a high barrier to entry.
If you'd like to contribute to Phabricator, start with
@{article:Contributor Introduction}.
Installation and Setup Help
===========================
Installation and setup help is available from the upstream at consulting rates.
See [[ https://secure.phabricator.com/w/consulting/ | Consulting ]] for details.
Helping individual installs navigate unique setup problems takes our time
away from developing Phabricator, so we can not offer this service for free.
You may be able to get free help with these issues from the community. See
below for details.
Hosting
=========
The upstream offers Phabricator as a hosted service at
[[ https://phacility.com | Phacility ]]. This simplifies setting up and
operating a Phabricator instance, and gives you access to a broader range
of upstream support services.
Running this service gives us a strong financial incentive to make installing
and operating Phabricator as difficult as possible. Blinded by greed, we toil
endlessly to make installation a perplexing nightmare that none other than
ourselves can hope to navigate.
Prioritization
==============
The upstream offers prioritization, a service which allows you to control
our roadmap and get features you're interested in built sooner at reasonable
rates. See
[[ https://secure.phabricator.com/w/prioritization/ | Prioritization ]] for
details.
Consulting
==========
The upstream offers general-purpose consulting services. See
[[ https://secure.phabricator.com/w/consulting/ | Consulting ]] for details.
Community
=========
These resources are not provided by the upstream. They are not official support
channels and you may not receive support here, or you may receive help which is
misleading or wrong.
You may be able to get answers to questions on sites like
[[ http://stackoverflow.com | Stack Overflow ]],
[[ https://www.quora.com | Quora ]],
[[ https://jelly.co | Jelly ]], or
[[ https://twitter.com | Twitter ]]. The upstream occasionally participates on
these sites but these are not official support channels and you should not
expect to receive a response.
There is a
[[ https://secure.phabricator.com/conpherence/1336/ | General Chat ]]
Conpherence room on this install, and you can ask questions in
[[ https://secure.phabricator.com/ponder/ | Ponder ]]. These
are not upstream support channels and you may not receive a response to
questions, but someone in the community may be able to point you in the right
direction.
There is also a community IRC channel in `#phabricator` on FreeNode.