Add/update contribution guidelines, issue/PR templates for GH Issues499-issue-work

4 files changed, 348 insertions, 15 deletions

diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md
new file mode 100644
index 000000000..be4f81685
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE.md
@@ -0,0 +1,32 @@
+<!--- Provide a general summary of the issue in the Title above -->
+
+## Expected Behavior
+<!--- If you're describing a bug, tell us what should happen -->
+<!--- If you're suggesting a change/improvement, tell us how it should work -->
+
+## Current Behavior
+<!--- If describing a bug, tell us what happens instead of the expected behavior -->
+<!--- If suggesting a change/improvement, explain the difference from current behavior -->
+
+## Possible Solution
+<!--- Not obligatory, but suggest a fix/reason for the bug, -->
+<!--- or ideas how to implement the addition or change -->
+
+## Steps to Reproduce (for bugs)
+<!--- Provide a link to a live example, or an unambiguous set of steps to -->
+<!--- reproduce this bug. Include code to reproduce, if relevant -->
+1.
+2.
+3.
+4.
+
+## Context
+<!--- How has this issue affected you? What are you trying to accomplish? -->
+<!--- Providing context helps us come up with a solution that is most useful in the real world -->
+
+## Your Environment
+<!--- Include as many relevant details about the environment you experienced the bug in -->
+* Version used:
+* Browser Name and version:
+* Operating System and version (desktop or mobile):
+* Link to your project:
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 71ea992ff..f364446c3 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,14 +1,15 @@
 <!-- Thank you for your contribution!
 
-     Please file this form by replacing markdown commentary
-     tags with the text. If section needs in no action - remove it.
+     Please file this form by replacing the Markdown comments
+     with your text. If a section needs no action - remove it.
 
      Also remember, that CouchDB uses the Review-Then-Commit (RTC) model
-     of code collaboration. Positive feedback provides by +1 from committers
-     while negative by -1. The -1 also means veto and need to be addressed
-     to find the consensus. Once there are no objections, PR could be merged.
+     of code collaboration. Positive feedback is represented +1 from committers
+     and negative is a -1. The -1 also means veto, and needs to be addressed
+     to proceed. Once there are no objections, the PR can be merged by a
+     CouchDB committer.
 
-     See: http://couchdb.apache.org/bylaws.html#decisions for more info -->
+     See: http://couchdb.apache.org/bylaws.html#decisions for more info. -->
 
 ## Overview
 
@@ -21,16 +22,17 @@
      Does it provides any behaviour that the end users
      could notice? -->
 
-## JIRA issue number
+## GitHub issue number
 
-<!-- If this is a significant change, please file a JIRA issue at:
-     https://issues.apache.org/jira/browse/COUCHDB
-     and include the number here and in commit message(s)  -->
+<!-- If this is a significant change, please file a separate issue at:
+     https://github.com/apache/couchdb/issues
+     and include the number here and in commit message(s) using
+     syntax like "Fixes #472" or "Fixes apache/couchdb#472".  -->
 
 ## Related Pull Requests
 
-<!-- If your changes affects on multiple components in different
-     repositories please list here links to those pull requests.  -->
+<!-- If your changes affects multiple components in different
+     repositories please put links to those pull requests here.  -->
 
 ## Checklist
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 000000000..884d3afbc
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,290 @@
+# Contributing to CouchDB
+
+Please take a moment to review this document in order to make the contribution
+process easy and effective for everyone involved.
+
+Following these guidelines helps to communicate that you respect the time of
+the developers managing and developing this open source project. In return,
+they should reciprocate that respect in addressing your issue, assessing
+changes, and helping you finalize your pull requests.
+
+Contributions to CouchDB are governed by our [Code of Conduct][6] and a set of
+[Project Bylaws][7]. Come join us!
+
+
+## Using the issue tracker
+
+First things first: **Do NOT report security vulnerabilities in public issues!**
+Please disclose responsibly by letting [the Apache CouchDB Security team](mailto:security@couchdb.apache.org?subject=Security)
+know upfront. We will assess the issue as soon as possible on a best-effort
+basis and will give you an estimate for when we have a fix and release available
+for an eventual public disclosure.
+
+The GitHub issue tracker is the preferred channel for [bug reports](#bugs),
+[features requests](#features) and [submitting pull requests](#pull-requests),
+but please respect the following restrictions:
+
+* Please **do not** use the issue tracker for personal support requests. Use
+  [CouchDB Chat][8] instead. Alternately, help us to help more people by
+  using our publicly archived [user][1] or [developer][5] mailing lists.
+
+* Please **do not** derail or troll issues. Keep the discussion on topic and
+  respect the opinions of others.
+
+
+## Bug reports
+
+A bug is a _demonstrable problem_ that is caused by the code in our
+repositories.  Good bug reports are extremely helpful - thank you!
+
+Guidelines for bug reports:
+
+1. **Use the GitHub issue search** &mdash; check if the issue has already been
+   reported.
+
+2. **Check if the issue has been fixed** &mdash; try to reproduce it using the
+   latest `master` or `next` branch in the repository.
+
+3. **Isolate the problem** &mdash; ideally create a reduced test case.
+
+A good bug report shouldn't leave others needing to chase you up for more
+information. Please try to be as detailed as possible in your report. What is
+your environment? What steps will reproduce the issue? What OS experiences the
+problem? What would you expect to be the outcome? All these details will help
+people to fix any potential bugs. Our issue template will help you include all
+of the relevant detail.
+
+Example:
+
+> Short and descriptive example bug report title
+>
+> A summary of the issue and the browser/OS environment in which it occurs. If
+> suitable, include the steps required to reproduce the bug.
+>
+> 1. This is the first step
+> 2. This is the second step
+> 3. Further steps, etc.
+>
+> `<url>` - a link to the reduced test case
+>
+> Any other information you want to share that is relevant to the issue being
+> reported. This might include the lines of code that you have identified as
+> causing the bug, and potential solutions (and your opinions on their
+> merits).
+
+
+## Feature requests
+
+Feature requests are welcome. But take a moment to find out whether your idea
+fits with the scope and aims of the project. It's up to *you* to make a strong
+case to convince the project's developers of the merits of this feature. Please
+provide as much detail and context as possible.
+
+
+## Pull requests
+
+Good pull requests - patches, improvements, new features - are a fantastic
+help. They should remain focused in scope and avoid containing unrelated
+commits.
+
+**Please ask first** before embarking on any significant pull request (e.g.
+implementing features, refactoring code), otherwise you risk spending a lot of
+time working on something that the project's developers might not want to merge
+into the project. You can talk with the community on our
+[developer mailing list][5].  We're always open to suggestions and will get
+back to you as soon as we can!
+
+
+### For new Contributors
+
+If you never created a pull request before, welcome :tada: :smile: [Here is a great tutorial](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github)
+on how to send one :)
+
+1. [Fork](http://help.github.com/fork-a-repo/) the project, clone your fork,
+   and configure the remotes:
+
+   ```bash
+   # Clone your fork of the repo into the current directory
+   git clone https://github.com/<your-username>/<repo-name>
+   # Navigate to the newly cloned directory
+   cd <repo-name>
+   # Assign the original repo to a remote called "upstream"
+   git remote add upstream https://github.com/apache/<repo-name>
+   ```
+
+2. If you cloned a while ago, get the latest changes from upstream:
+
+   ```bash
+   git checkout master
+   git pull upstream master
+   ```
+
+3. Create a new topic branch (off the main project development branch) to
+   contain your feature, change, or fix:
+
+   ```bash
+   git checkout -b <topic-branch-name>
+   ```
+
+4. Make sure to update, or add to the tests when appropriate. Patches and
+   features will not be accepted without tests. Run `make check` to check that
+   all tests pass after you've made changes. Look for a `Testing` section in
+   the project’s README for more information.
+
+5. If you added or changed a feature, make sure to document it accordingly in
+   the [CouchDB documentation](https://github.com/apache/couchdb-documentation)
+   repository.
+
+6. Push your topic branch up to your fork:
+
+   ```bash
+   git push origin <topic-branch-name>
+   ```
+
+8. [Open a Pull Request](https://help.github.com/articles/using-pull-requests/)
+    with a clear title and description.
+
+
+### For Apache CouchDB Committers
+
+1. Be sure to set up [GitHub two-factor authentication](https://help.github.com/articles/about-two-factor-authentication/),
+   then [link your Apache account to your GitHub account](https://gitbox.apache.org/setup/).
+   You will need to wait about 30 minutes after completing this process
+   for it to complete. Follow the instructions in the organisational
+   invite email you receive. Alternately, you can use the Apache mirror
+   of the repository at `https://gitbox.apache.org/asf/repos/<name>.git`
+   if you do not agree to the GitHub Terms of Service.
+
+2. Clone the repo and create a branch.
+
+   ```bash
+   git clone https://github.com/couchdb/<repo-name>
+   # or git clone https://gitbox.apache.org/asf/repos/<name>.git
+   cd <repo-name>
+   git checkout -b <topic-branch-name>
+   ```
+
+3. Make sure to update, or add to the tests when appropriate. Patches and
+   features will not be accepted without tests. Run `make check` to check that
+   all tests pass after you've made changes. Look for a `Testing` section in
+   the project’s README for more information.
+
+4. If you added or changed a feature, make sure to document it accordingly in
+   the [CouchDB documentation](https://github.com/apache/couchdb-documentation)
+   repository.
+
+5. Push your topic branch up to our repo
+
+   ```bash
+   git push origin <topic-branch-name>
+   ```
+
+6. Open a Pull Request using your branch with a clear title and description.
+   Please also add any appropriate labels to the pull request for clarity.
+
+Optionally, you can help us with these things. But don’t worry if they are too
+complicated, we can help you out and teach you as we go :)
+
+1. Update your branch to the latest changes in the upstream master branch. You
+   can do that locally with
+
+   ```bash
+   git pull --rebase upstream master
+   ```
+
+   Afterwards force push your changes to your remote feature branch.
+
+2. Once a pull request is good to go, you can tidy up your commit messages using
+   Git's [interactive rebase](https://help.github.com/articles/interactive-rebase).
+
+**IMPORTANT**: By submitting a patch, you agree to license your work under the
+Apache License, per your signed Apache CLA.
+
+
+## Triagers
+
+Apache CouchDB committers who have completed the GitHub account linking
+process may triage issues. This helps to speed up releases and minimises both
+user and developer pain in working through our backlog.
+
+Briefly, to triage an issue, review the report, validate that it is an actual
+issue (reproducing if possible), and add one or more labels. We have a
+[summary of our label taxonomy](https://github.com/apache/couchdb/issues/499)
+for your reference.
+
+If you are not an official committer, please reach out to our [mailing list][5]
+or [chat][8] to learn how you can assist with triaging indirectly.
+
+
+## Maintainers
+
+If you have commit access, please follow this process for merging patches and cutting new releases.
+
+### Reviewing changes
+
+1. Check that a change is within the scope and philosophy of the component.
+2. Check that a change has any necessary tests.
+3. Check that a change has any necessary documentation.
+4. If there is anything you don’t like, leave a comment below the respective
+   lines and submit a "Request changes" review. Repeat until everything has
+   been addressed.
+5. If you are not sure about something, mention specific people for help in a
+   comment.
+6. If there is only a tiny change left before you can merge it and you think
+   it’s best to fix it yourself, you can directly commit to the author’s fork.
+   Leave a comment about it so the author and others will know.
+7. Once everything looks good, add an "Approve" review. Don’t forget to say
+   something nice 👏🐶💖✨
+8. If the commit messages follow [our conventions](@commit-message-conventions)
+
+   1. If the pull request fixes one or more open issues, please include the
+      text "Fixes #472" or "Fixes apache/couchdb#472". 
+   2. Use the "Rebase and merge" button to merge the pull request.
+   3. Done! You are awesome! Thanks so much for your help 🤗
+
+9. If the commit messages _do not_ follow our conventions
+
+   1. Use the "squash and merge" button to clean up the commits and merge at
+      the same time: ✨🎩
+   2. If the pull request fixes one or more open issues, please include the
+      text "Fixes #472" or "Fixes apache/couchdb#472". 
+
+Sometimes there might be a good reason to merge changes locally. The process
+looks like this:
+
+### Reviewing and merging changes locally
+
+```
+git checkout master # or the main branch configured on github
+git pull # get latest changes
+git checkout feature-branch # replace name with your branch
+git rebase master
+git checkout master
+git merge feature-branch # replace name with your branch
+git push
+```
+
+When merging PRs from forked repositories, we recommend you install the
+[hub](https://github.com/github/hub) command line tools.
+
+This allows you to do:
+
+```
+hub checkout link-to-pull-request
+```
+
+meaning that you will automatically check out the branch for the pull request,
+without needing any other steps like setting git upstreams! :sparkles:
+
+
+## Thanks
+
+Special thanks to [Hoodie][https://github.com/hoodiehq/hoodie] for the great
+CONTRIBUTING.md template.
+
+[1]: http://mail-archives.apache.org/mod_mbox/couchdb-user/
+[5]: http://mail-archives.apache.org/mod_mbox/couchdb-dev/
+[6]: http://couchdb.apache.org/conduct.html
+[7]: http://couchdb.apache.org/bylaws.html
+[8]: http://couchdb.apache.org/#chat
+
diff --git a/README.rst b/README.rst
index 35adaaed3..5e435b583 100644
--- a/README.rst
+++ b/README.rst
@@ -1,13 +1,15 @@
 Apache CouchDB README
 =====================
 
-Travis CI master build status: |travisci|
++--------------------------------+------------+
+| Travis CI master build status  | |travisci| |
++--------------------------------+------------+
+| Jenkins CI master build status | |jenkins|  |
++--------------------------------+------------+
 
 .. |travisci| image:: https://travis-ci.org/apache/couchdb.svg?branch=master
     :target: https://travis-ci.org/apache/couchdb
 
-Jenkins CI master build status: |jenkins|
-
 .. |jenkins| image:: https://builds.apache.org/buildStatus/icon?job=CouchDB
     :target: https://builds.apache.org/job/CouchDB/
 
@@ -79,6 +81,13 @@ Fauxton. To fix the admin party you have to run ``./dev/run`` with the ``admin``
 flag, e.g. ``./dev/run --admin=username:password``. If you want to have an
 admin-party, just omit the flag.
 
+Contributing to CouchDB
+-----------------------
+
+You can learn more about our contributing process here:
+
+    https://github.com/apache/couchdb/blob/master/CONTRIBUTING.md
+
 Cryptographic Software Notice
 -----------------------------