diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c9540f41f2ff..3642b118ec9d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,92 +1,113 @@ # 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 + +1. Clone your fork of the GitHub repository -2. Clone your fork of the GitHub repository + ```sh + git clone git@github.com:/druid.git + ``` -```sh -git clone git@github.com:/druid.git -``` + replace `` with your GitHub username. -Add a remote to keep up with upstream changes +1. Add a remote to keep up with upstream changes -``` -git remote add upstream https://github.com/druid-io/druid.git -``` + ``` + git remote add upstream https://github.com/druid-io/druid.git + ``` -If you already have a copy, fetch upstream changes + If you already have a copy, fetch upstream changes -``` -git fetch upstream -``` + ``` + 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 -``` + ``` + git checkout -b feature-xxx remotes/upstream/master + ``` -4. Work in your feature branch +1. Work in your feature branch -``` -git commit -a -``` + ``` + git commit -a + ``` -5. Periodically rebase your changes +1. Periodically rebase your changes -``` -git pull --rebase -``` + ``` + 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 -``` + ``` + 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 -``` + ``` + git push origin feature-xxx + ``` -Go to your Druid fork main page + Go to your Druid fork main page -https://github.com//druid + https://github.com//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 -click that button it will automatically offer you to submit your pull-request -to the druid-io/druid repository. + 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 + click that button it will automatically offer you to submit your pull-request + 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. + - 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. + Repeat steps 4. through 6. to address any code review comments and + rebase your changes if necessary. -Push your updated changes to update the pull request + Push your updated changes to update the pull request -``` -git push origin [--force] feature-xxx -``` + ``` + git push origin [--force] feature-xxx + ``` -`--force` may be necessary to overwrite your existing pull request in case your -commit history was changed when performing the rebase. + `--force` may be necessary to overwrite your existing pull request in case your + commit history was changed when performing the rebase. -Note: Be careful when using `--force` since you may lose data if you are not careful. + Note: Be careful when using `--force` since you may lose data if you are not careful. -``` -git push origin --force feature-xxx -``` + ``` + git push origin --force feature-xxx + ``` # FAQ @@ -95,27 +116,27 @@ 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 -``` + ``` + 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 -``` + ``` + 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 -``` + ``` + 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 -``` + ``` + git push origin [--force] feature-xxx:feature-xxx + ```