Merge pull request #1083 from metamx/contrib-docs

Provide more guidelines for contributing

CONTRIBUTING.md

@@ -1,18 +1,37 @@
 # How to Contribute
 
+When submitting a pull request (PR), please use the following guidelines:
+
+- Try to keep pull requests short and submit separate ones for unrelated
+  features, but feel free to combine simple bugfixes/tests into one pull request.
+- Keep the number of commits small and combine commits for related changes.
+  Each commit should compile on its own and ideally pass tests.
+- If you are introducing a new feature you may want to first submit your idea
+  of feedback in the [mailing list](mailto:druid-development@googlegroups.com).
+- Bugfixes should include a unit-test or integration test reproducing the issue.
+- Non-trivial features should include unit-test covering the new functionality.
+- Make sure your code respects existing formatting conventions. We don't have a
+  formal style guide yet, but use your own judgement. If you are using
+  IntelliJ, you can use import our code style settings jar
+  [intellij_formatting.jar](https://github.com/druid-io/druid/raw/master/intellij_formatting.jar).
+- Keep formatting changes in separate commits to make code reviews easier and
+  distinguish them from actual code changes.
+
 ## GitHub Workflow
 
 1. Fork the druid-io/druid repository into your GitHub account
 
-https://github.com/druid-io/druid
+  https://github.com/druid-io/druid/fork
 
-2. Clone your fork of the GitHub repository
+1. Clone your fork of the GitHub repository
 
   ```sh
-git clone git@github.com:<ghuser>/druid.git
+  git clone git@github.com:<username>/druid.git
   ```
 
-Add a remote to keep up with upstream changes
+  replace `<username>` with your GitHub username.
+
+1. Add a remote to keep up with upstream changes
 
   ```
   git remote add upstream https://github.com/druid-io/druid.git
@@ -24,33 +43,35 @@ If you already have a copy, fetch upstream changes
   git fetch upstream
   ```
 
-3. Create a feature branch to work in
+1. Create a feature branch to work in
 
   ```
   git checkout -b feature-xxx remotes/upstream/master
   ```
 
-4. Work in your feature branch
+1. Work in your feature branch
 
   ```
   git commit -a
   ```
 
-5. Periodically rebase your changes
+1. Periodically rebase your changes
 
   ```
   git pull --rebase
   ```
 
-6. When done, "squash" your commits
+1. When done, combine ("squash") related commits into a single one
 
   ```
   git rebase -i upstream/master
   ```
 
-Prefix commits using `s` (squash) or `f` (fixup) to merge extraneous commits.
+  This will open your editor and allow you to re-order commits and merge them:
+  - Re-order the lines to change commit order (to the extent possible without creating conflicts)
+  - Prefix commits using `s` (squash) or `f` (fixup) to merge extraneous commits.
 
-7. Submit a pull-request
+1. Submit a pull-request
 
   ```
   git push origin feature-xxx
@@ -58,7 +79,7 @@ git push origin feature-xxx
 
   Go to your Druid fork main page
 
-https://github.com/<ghuser>/druid
+  https://github.com/<username>/druid
 
   If you recently pushed your changes GitHub will automatically pop up a
   `Compare & pull request` button for any branches you recently pushed to. If you
@@ -68,7 +89,7 @@ to the druid-io/druid repository.
   - Give your pull-request a meaningful title.
   - In the description, explain your changes and the problem they are solving.
 
-8. Addressing code review comments
+1. Addressing code review comments
 
   Repeat steps 4. through 6. to address any code review comments and
   rebase your changes if necessary.
@@ -95,26 +116,26 @@ git push origin --force feature-xxx
 
 Never fear, if you occasionally merged upgstream/master, here is another way to squash your changes into a single commit
 
-Rename your existing branch first
+1. First, rename your existing branch to something else, e.g. `feature-xxx-unclean`
 
   ```
   git branch -m feature-xxx-unclean
   ```
 
-Checkout a new branch with the original name `feature-xxx` from upstream. This branch will supercede our old one.
+1. Checkout a new branch with the original name `feature-xxx` from upstream. This branch will supercede our old one.
 
   ```
   git checkout -b feature-xxx upstream/master
   ```
 
-Then merge your changes in your original feature branch `feature-xxx-unclean` and create a single commit.
+1. Then merge your changes in your original feature branch `feature-xxx-unclean` and create a single commit.
 
   ```
   git merge --squash feature-xxx-unclean
   git commit
   ```
 
-You can now submit this new branch and create or replace your existing pull request
+1. You can now submit this new branch and create or replace your existing pull request
 
   ```
   git push origin [--force] feature-xxx:feature-xxx