druid/CONTRIBUTING.md

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.
• 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.
• 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/fork

1. Clone your fork of the GitHub repository

git clone git@github.com:<username>/druid.git

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

If you already have a copy, fetch upstream changes

git fetch upstream

1. Create a feature branch to work in

git checkout -b feature-xxx remotes/upstream/master

1. Work in your feature branch

git commit -a

1. Periodically rebase your changes

git pull --rebase

1. When done, combine ("squash") related commits into a single one

git rebase -i upstream/master

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.

1. Submit a pull-request

git push origin feature-xxx

Go to your Druid fork main page

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 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.

1. Addressing code review comments

Repeat steps 5. through 7. to address any code review comments and rebase your changes if necessary.

Push your updated changes to update the pull request

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.

Note: Be careful when using --force since you may lose data if you are not careful.

git push origin --force feature-xxx

FAQ

Help! I merged changes from upstream and cannot figure out how to resolve conflits when rebasing!

Never fear, if you occasionally merged upgstream/master, here is another way to squash your changes into a single commit

1. First, rename your existing branch to something else, e.g. feature-xxx-unclean

git branch -m feature-xxx-unclean

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

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

1. You can now submit this new branch and create or replace your existing pull request

git push origin [--force] feature-xxx:feature-xxx