Merge branch 'docs/contributing' into next

CONTRIBUTING.md

@@ -1,14 +1,23 @@
 # Contributing to Kong
 
-## Got a question or problem?
+### Got a question or problem?
 
-Discuss it on the [Google Group](https://groups.google.com/forum/#!forum/konglayer) or chat with us on [Gitter](https://gitter.im/Mashape/kong).
+Discuss it on the [Google Group](https://groups.google.com/forum/#!forum/konglayer) or chat with us on [Gitter](https://gitter.im/Mashape/kong) or freenode in [#kong](http://webchat.freenode.net/?channels=kong).
 
-## Found a bug?
+### Browsing the code?
 
-We would like to hear about it. Please [submit an issue][new-issue] on GitHub and we will follow up. Even better, we would appreciate a [Pull Request][new-pr] (against the `next` branch) with a fix for it. If the fix is urgent, feel free to open the PR against the `master` branch.
+We work on two branches: `master` for stable, released code and `next`, a development branch. It might be important to distinguish them when you are reading the commit history searching for a feature or a bugfix, or when you are unsure of where to base your work from when contributing.
 
-## Want a feature?
+### Found a bug?
+
+We would like to hear about it. Please [submit an issue][new-issue] on GitHub and we will follow up. Even better, we would appreciate a [Pull Request][new-pr] with a fix for it!
+
+- If the bug was found in a release, it is best to base your work on `master` and submit your PR against it.
+- If the bug was found on `next` (the development branch), base your work on `next` and submit your PR against it.
+
+Please follow the [Pull Request Guidelines][new-pr].
+
+### Want a feature?
 
 Feel free to request a feature by [submitting an issue][new-issue] on GitHub and open the discussion.
 
@@ -22,22 +31,68 @@ Before you submit an issue, search the archive, maybe you will find that a simil
 
 If you are submitting an issue for a bug, please include the following:
 
-- The platform you are running Kong on
+- An overview of the issue
+- Your use case (why is this a bug for you?)
 - The version of Kong you are running
+- The platform you are running Kong on
 - Steps to reproduce the issue
 - Eventually, logs from your `error.log` file. You can find this file at `<nginx_working_dir>/logs/error.log`
+- Ideally, a suggested fix
+
+The more informations you give us, the more able to help we will be!
 
 ### Submitting a Pull Request
 
-Before submitting your Pull Request please make sure to:
+- First of all, make sure to base your work on the `next` branch (the development branch):
+
+  ```
+  # a bugfix branch for next would be prefixed by fix/
+  # a bugfix branch for master would be prefixed by hotfix/
+  $ git checkout -b feature/my-feature next
+  ```
+
+- Please create commits containing **related changes**. For example, two different bugfixes should produce two separate commits. A feature should be made of commits splitted by **logical chunks** (no half-done changes). Use your best judgement as to how many commits your changes require.
+
+- Write insightful and descriptive commit messages. It lets us and future contributors quickly understand your changes without having to read your changes. Please provide a summary in the first line (50-72 characters) and eventually, go to greater lengths in your message's body. We also like commit message with a **type** and **scope**. We generally follow the [Angular commit message format](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit-message-format).
+
+- Please **include the appropriate test cases** for your patch.
+
+- Make sure all tests pass before submitting your changes. See the [Makefile operations](/README.md#makefile-operations).
+
+- Make sure the linter does not throw any error: `make lint`.
+
+- Rebase your commits. It may be that new commits have been introduced on `next`. Rebasing will update your branch with the most recent code and make your changes easier to review:
+
+  ```
+  $ git fetch
+  $ git rebase origin/next
+  ```
+
+- Push your changes:
+
+  ```
+  $ git push origin -u feature/my-feature
+  ```
+
+- Open a pull request against the `next` branch.
+
+- If we suggest changes:
+  - Please make the required updates (after discussion if any)
+  - Only create new commits if it makes sense. Generally, you will want to amend your latest commit or rebase your branch after the new changes:
+
+    ```
+    $ git rebase -i next
+    # choose which commits to edit and perform the updates
+    ```
+
+  - Re-run the test suite
+  - Force push to your branch:
 
-- Make the Pull Request against the `next` branch. If it's an urgent bugfix, then use the `master` branch.
-- Include tests with your changes. If your changes introduce a new feature, please include tests with it. If it fixes a bug, please create a test to validate the fix.
-- Rebase your commits. It may be that new commits have been introduced on the branch your are opening your Pull Request against. Rebasing will update your branch with the most resent code and make your changes easier to review.
-- Consider squashing your commits. We prefer your initial changes to be squashed into a single commit. Later, if we ask you to make changes, add them as separate commits. This makes them easier to review. As a final step before merging we will either ask you to squash all commits yourself or we'll do it for you.
-- Run the test suite with `make test-all`.
+    ```
+    $ git push origin feature/my-feature -f
+    ```
 
-If all went well, we are eager to see your contribution, feel free to submit your Pull Request against the `next` branch.
+We are eager to see your contribution!
 
 [new-issue]: #submitting-an-issue
 [new-pr]: #submitting-a-pull-request