Add GitHub issue and pull request templates, update CONTRIBUTING.md

3 files changed, 168 insertions, 22 deletions

diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md
new file mode 100644
index 0000000000..70b54cd818
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE.md
@@ -0,0 +1,43 @@
+Thank you for using RabbitMQ and for taking the time to report an
+issue.
+
+## Does This Belong to GitHub or RabbitMQ Mailing List?
+
+*Important:* please first read the `CONTRIBUTING.md` document in the
+root of this repository. It will help you determine whether your
+feedback should be directed to the RabbitMQ mailing list [1] instead.
+
+## Please Help Maintainers and Contributors Help You
+
+In order for the RabbitMQ team to investigate your issue, please provide
+**as much as possible** of the following details:
+
+* RabbitMQ version
+* Erlang version
+* RabbitMQ server and client application log files
+* A runnable code sample, terminal transcript or detailed set of
+  instructions that can be used to reproduce the issue
+* RabbitMQ plugin information via `rabbitmq-plugins list`
+* Client library version (for all libraries used)
+* Operating system, version, and patch level
+
+Running the `rabbitmq-collect-env` [2] script can provide most of the
+information needed. Please make the archive available via a third-party
+service and note that **the script does not attempt to scrub any
+sensitive data**.
+
+If your issue involves RabbitMQ management UI or HTTP API, please also provide
+the following:
+
+ * Browser and its version
+ * What management UI page was used (if applicable)
+ * How the HTTP API requests performed can be reproduced with `curl`
+ * Operating system on which you are running your browser, and its version
+ * Errors reported in the JavaScript console (if any)
+
+This information **greatly speeds up issue investigation** (or makes it
+possible to investigate it at all).  Please help project maintainers and
+contributors to help you by providing it!
+
+1. https://groups.google.com/forum/#!forum/rabbitmq-users
+2. https://github.com/rabbitmq/support-tools/blob/master/scripts/rabbitmq-collect-env
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000000..4bd618567b
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,43 @@
+## Proposed Changes
+
+Please describe the big picture of your changes here to communicate to the
+RabbitMQ team why we should accept this pull request. If it fixes a bug or
+resolves a feature request, be sure to link to that issue.
+
+A pull request that doesn't explain **why** the change was made has a much
+lower chance of being accepted.
+
+If English isn't your first language, don't worry about it and try to
+communicate the problem you are trying to solve to the best of your abilities.
+As long as we can understand the intent, it's all good.
+
+## Types of Changes
+
+What types of changes does your code introduce to this project?
+_Put an `x` in the boxes that apply_
+
+- [ ] Bugfix (non-breaking change which fixes issue #NNNN)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation (correction or otherwise)
+- [ ] Cosmetics (whitespace, appearance)
+
+## Checklist
+
+_Put an `x` in the boxes that apply. You can also fill these out after creating
+the PR. If you're unsure about any of them, don't hesitate to ask on the
+mailing list. We're here to help! This is simply a reminder of what we are
+going to look for before merging your code._
+
+- [ ] I have read the `CONTRIBUTING.md` document
+- [ ] I have signed the CA (see https://cla.pivotal.io/sign/rabbitmq)
+- [ ] All tests pass locally with my changes
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] I have added necessary documentation (if appropriate)
+- [ ] Any dependent changes have been merged and published in related repositories
+
+## Further Comments
+
+If this is a relatively large or complex change, kick off the discussion by
+explaining why you chose the solution you did and what alternatives you
+considered, etc.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index daaea42b18..29c7fa2748 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,29 +1,80 @@
+Thank you for using RabbitMQ and for taking the time to contribute to the project.
+This document has two main parts:
+
+ * when and how to file GitHub issues for RabbitMQ projects
+ * how to submit pull requests
+
+They intend to save you and RabbitMQ maintainers some time, so please
+take a moment to read through them.
+
 ## Overview
 
-RabbitMQ projects use pull requests to discuss, collaborate on and accept code contributions.
-Pull requests is the primary place of discussing code changes.
+### GitHub issues
 
-## How to Contribute
+The RabbitMQ team uses GitHub issues for _specific actionable items_ that
+engineers can work on. This assumes the following:
 
-The process is fairly standard:
+* GitHub issues are not used for questions, investigations, root cause
+  analysis, discussions of potential issues, etc (as defined by this team)
+* Enough information is provided by the reporter for maintainers to work with
 
- * Fork the repository or repositories you plan on contributing to
- * Clone [RabbitMQ umbrella repository](https://github.com/rabbitmq/rabbitmq-public-umbrella)
- * `cd umbrella`, `make co`
- * Create a branch with a descriptive name in the relevant repositories
- * Make your changes, run tests, commit with a [descriptive message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), push to your fork
- * Submit pull requests with an explanation what has been changed and **why**
- * Submit a filled out and signed [Contributor Agreement](https://github.com/rabbitmq/ca#how-to-submit) if needed (see below)
- * Be patient. We will get to your pull request eventually
+The team receives many questions through various venues every single
+day. Frequently, these questions do not include the necessary details
+the team needs to begin useful work. GitHub issues can very quickly
+turn into a something impossible to navigate and make sense
+of. Because of this, questions, investigations, root cause analysis,
+and discussions of potential features are all considered to be
+[mailing list][rmq-users] material. If you are unsure where to begin,
+the [RabbitMQ users mailing list][rmq-users] is the right place.
 
-If what you are going to work on is a substantial change, please first ask the core team
-of their opinion on [RabbitMQ mailing list](https://groups.google.com/forum/#!forum/rabbitmq-users).
+Getting all the details necessary to reproduce an issue, make a
+conclusion or even form a hypothesis about what's happening can take a
+fair amount of time. Please help others help you by providing a way to
+reproduce the behavior you're observing, or at least sharing as much
+relevant information as possible on the [RabbitMQ users mailing
+list][rmq-users].
 
+Please provide versions of the software used:
 
-## Code of Conduct
+ * RabbitMQ server
+ * Erlang
+ * Operating system version (and distribution, if applicable)
+ * All client libraries used
+ * RabbitMQ plugins (if applicable)
 
-See [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).
+The following information greatly helps in investigating and reproducing issues:
+
+ * RabbitMQ server logs
+ * A code example or terminal transcript that can be used to reproduce
+ * Full exception stack traces (a single line message is not enough!)
+ * `rabbitmqctl report` and `rabbitmqctl environment` output
+ * Other relevant details about the environment and workload, e.g. a traffic capture
+ * Feel free to edit out hostnames and other potentially sensitive information.
+
+To make collecting much of this and other environment information, use
+the [`rabbitmq-collect-env`][rmq-collect-env] script. It will produce an archive with
+server logs, operating system logs, output of certain diagnostics commands and so on.
+Please note that **no effort is made to scrub any information that may be sensitive**.
+
+### Pull Requests
 
+RabbitMQ projects use pull requests to discuss, collaborate on and accept code contributions.
+Pull requests is the primary place of discussing code changes.
+
+Here's the recommended workflow:
+
+ * [Fork the repository][github-fork] or repositories you plan on contributing to. If multiple
+   repositories are involved in addressing the same issue, please use the same branch name
+   in each repository
+ * Create a branch with a descriptive name in the relevant repositories
+ * Make your changes, run tests (usually with `make tests`), commit with a
+   [descriptive message][git-commit-msgs], push to your fork
+ * Submit pull requests with an explanation what has been changed and **why**
+ * Submit a filled out and signed [Contributor Agreement][ca-agreement] if needed (see below)
+ * Be patient. We will get to your pull request eventually
+
+If what you are going to work on is a substantial change, please first
+ask the core team for their opinion on the [RabbitMQ users mailing list][rmq-users].
 
 ## Running Tests
 
@@ -49,15 +100,24 @@ Finally,
 
 will run all suites.
 
+## Code of Conduct
 
-## Contributor Agreement
+See [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).
 
-If you want to contribute a non-trivial change, please submit a signed copy of our
-[Contributor Agreement](https://github.com/rabbitmq/ca#how-to-submit) around the time
-you submit your pull request. This will make it much easier (in some cases, possible)
-for the RabbitMQ team at Pivotal to merge your contribution.
+## Contributor Agreement
 
+If you want to contribute a non-trivial change, please submit a signed
+copy of our [Contributor Agreement][ca-agreement] around the time you
+submit your pull request. This will make it much easier (in some
+cases, possible) for the RabbitMQ team at Pivotal to merge your
+contribution.
 
 ## Where to Ask Questions
 
-If something isn't clear, feel free to ask on our [mailing list](https://groups.google.com/forum/#!forum/rabbitmq-users).
+If something isn't clear, feel free to ask on our [mailing list][rmq-users].
+
+[rmq-collect-env]: https://github.com/rabbitmq/support-tools/blob/master/scripts/rabbitmq-collect-env
+[git-commit-msgs]: https://goo.gl/xwWq
+[rmq-users]: https://groups.google.com/forum/#!forum/rabbitmq-users
+[ca-agreement]: https://cla.pivotal.io/sign/rabbitmq
+[github-fork]: https://help.github.com/articles/fork-a-repo/