Merge pull request #176 from bigchaindb/feat/175/update-contributing-md

CONTRIBUTING.md: a PR should resolve an existing issue

CONTRIBUTING.md

@@ -12,7 +12,17 @@ If you want to file a bug report, suggest a feature, or ask a code-related quest
 
 ## How to Contribute Code or Documentation
 
-### Step 0 - Prepare and Familiarize Yourself
+### Step 0 - Decide on an Issue to Resolve, or Create One
+
+We want you to feel like your contributions (pull requests) are welcome, but if you contribute something unnecessary, unwanted, or perplexing, then your experience may be unpleasant. Your pull request may sit gathering dust as everyone scratches their heads wondering what to do with it.
+
+To prevent that situation, we ask that all pull requests should resolve, address, or fix an existing issue. If there is no existing issue, then you should create one first. That way there can be commentary and discussion first, and you can have a better idea of what to expect when you create a corresponding pull request.
+
+When you submit a pull request, please mention the issue (or issues) that it resolves, e.g. "Resolves #123".
+
+Exception: hotfixes and minor changes don't require a pre-existing issue, but please write a thorough pull request description.
+
+### Step 1 - Prepare and Familiarize Yourself
 
 To contribute code or documentation, you need a [GitHub account](https://github.com/signup/free).
 
@@ -25,11 +35,11 @@ Familiarize yourself with how we do coding and documentation in the BigchainDB p
     * [Scott Chacon's blog post about GitHub Flow](http://scottchacon.com/2011/08/31/github-flow.html)
 * [semantic versioning](http://semver.org/)
 
-### Step 1 - Fork bigchaindb on GitHub
+### Step 2 - Fork bigchaindb on GitHub
 
 In your web browser, go to [the BigchainDB repository on GitHub](https://github.com/bigchaindb/bigchaindb) and click the `Fork` button in the top right corner. This creates a new Git repository named `bigchaindb` in _your_ GitHub account.
 
-### Step 2 - Clone Your Fork
+### Step 3 - Clone Your Fork
 
 (This only has to be done once.) In your local terminal, use Git to clone _your_ `bigchaindb` repository to your local computer. Also add the original GitHub bigchaindb/bigchaindb repository as a remote named `upstream` (a convention):
 ```text
@@ -38,7 +48,7 @@ cd bigchaindb
 git add upstream git@github.com:bigchaindb/bigchaindb.git
 ```
 
-### Step 3 - Fetch and Merge the Latest from `upstream/master`
+### Step 4 - Fetch and Merge the Latest from `upstream/master`
 
 Switch to the `master` branch locally, fetch all `upstream` branches, and merge the just-fetched `upstream/master` branch with the local `master` branch:
 ```text
@@ -47,7 +57,7 @@ git fetch upstream
 git merge upstream/master
 ```
 
-### Step 4 - Create a New Branch for Each Bug/Feature
+### Step 5 - Create a New Branch for Each Bug/Feature
 
 If your new branch is to **fix a bug** identified in a specific GitHub Issue with number `ISSNO`, then name your new branch `bug/ISSNO/short-description-here`. For example, `bug/67/fix-leap-year-crash`.
 
@@ -58,7 +68,7 @@ Otherwise, please give your new branch a short, descriptive, all-lowercase name.
 git checkout -b new-branch-name
 ```
 
-### Step 5 - Make Edits, git add, git commit
+### Step 6 - Make Edits, git add, git commit
 
 With your new branch checked out locally, make changes or additions to the code or documentation. Remember to:
 
@@ -85,14 +95,14 @@ If your addition or change is substantial, then please add a line or two to the
 
 (When you submit your pull request [following the instructions below], we run all the tests automatically, so we will see if some are failing. If you don't know why some tests are failing, you can still submit your pull request, but be sure to note the failing tests and to ask for help with resolving them.)
 
-### Step 6 - Push Your New Branch to origin
+### Step 7 - Push Your New Branch to origin
 
 Make sure you've commited all the additions or changes you want to include in your pull request. Then push your new branch to origin (i.e. _your_ remote bigchaindb repository).
 ```text
 git push origin new-branch-name
 ```
 
-### Step 7 - Create a Pull Request 
+### Step 8 - Create a Pull Request 
 
 Go to the GitHub website and to _your_ remote bigchaindb repository (i.e. something like https://github.com/your-user-name/bigchaindb).