Skip to content

Latest commit

 

History

History
210 lines (150 loc) · 8.97 KB

CONTRIBUTING.md

File metadata and controls

210 lines (150 loc) · 8.97 KB
Raw

How to Contribute

When submitting a pull request (PR), please use the following guidelines:

  • A description of style conventions can be found at dev/style-conventions.md
  • Make sure your code respects existing formatting conventions. In general, follow the same coding style as the code that you are modifying.
  • For Intellij you can import our code style settings xml: druid_intellij_formatting.xml.
  • For Eclipse you can import our code style settings xml: eclipse_formatting.xml.
  • Do add/update documentation appropriately for the change you are making.
  • If you are introducing a new feature you may want to first write about your idea for feedback to dev@druid.apache.org. Or create an issue using "Feature/Change" template. Non-trivial features should include unit tests covering the new functionality. Open a "Proposal" issue for large changes.
  • Bugfixes should include a unit test or integration test reproducing the issue.
  • Do not use author tags/information in the code.
  • 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.
  • If you are adding or updating a dependency, be sure to update the version, license, or notice information in licenses.yaml as appropriate to help ease LICENSE and NOTICE management for ASF releases.

You can find more developers' resources in dev/ directory.

GitHub Workflow

  1. Fork the apache/druid repository into your GitHub account

    https://github.com/apache/druid/fork

  2. Clone your fork of the GitHub repository

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

    replace <username> with your GitHub username.

  3. Add a remote to keep up with upstream changes

    git remote add upstream https://github.com/apache/druid.git

    If you already have a copy, fetch upstream changes

    git fetch upstream master

  4. Create a feature branch to work in

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

  5. Before submitting a pull request periodically rebase your changes (but don't do it when a pull request is already submitted)

    git pull --rebase upstream master

  6. Before submitting a pull request, 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.

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

    Address code review comments by committing changes and pushing them to your feature branch.

    git push origin feature-xxx

If your pull request shows conflicts with master

If your pull request shows conflicts with master, merge master into your feature branch:

git merge upstream/master

and resolve the conflicts. After resolving conflicts, push your branch again:

git push origin feature-xxx

Avoid rebasing and force pushes after submitting a pull request, since these make it difficult for reviewers to see what you've changed in response to their reviews. The Druid committer that merges your change will rebase and squash it into a single commit before committing it to master.

Release notes

Release notes are the way that Druid users will learn about your fix or improvement. What does a user need to know? The key is to identify the user impact. Give it your best shot! Druid committers will review and edit your notes.

Here's a non-exhaustive list of the type of changes that have user impact and need release notes:

  • Changes what the user sees in the UI.
  • Changes any action that the user takes (in the UI, in the API, in configuration, in install, etc.)
  • Changes the results of any query, ingestion, or task.
  • Changes performance (preferably making things faster).
  • Adds, deprecates, or removes features.
  • Anything that changes install, configuration, or operation of Druid.

An example of a change that doesn't need a release note is fixing a flakey test.

Use these tips when writing your release note:

Summarize your change. Describe the user impacting parts of your change, but try to be as concise as you can.

Be accurate, clear, and concise. If you can't tick all of these off, the order of priority is accurate > clear > concise.

WIIFM - what's in it for me? Spell out why the user should care. A release note shouldn't be like a stand-up update that focuses on the details of code changes.

Give enough context. Make sure there's enough detail for users to do something with the information if they need to. For example, include the property they need to set and link to the documentation when possible.

You don't need to be formal and impersonal. Speak directly to the user ("You can..."). Avoid passive voice (“X has been added”).

Example release notes

Template Examples
New: You can now… New: You can now upload CSV files with a single header row for batch ingestion. Set the inferSchemaFromHeader property of your ingestion spec to true to enable this feature. For more information, see TITLE.
Fixed: X no longer does Y when Z. Fixed: Multi-value string array expressions no longer give flattened results when used in groupBy queries.
Changed: X now does Y. Previously, X did Z. Changed: The first/last string aggregator now only compares based on values. Previously, the first/last string aggregator’s values were compared based on the _time column first and then on values.
Improved: Better / Increased / Updated etc. Improved: You can now perform Kinesis ingestion even if there are empty shards. Previously, all shards had to have at least one record.
Improved: Better / Increased / Updated etc. Improved: Java 11 is fully supported and is no longer experimental. Java 17 support is improved.
Deprecated: Removed / Will remove X. Deprecated: Support for ZooKeeper X.Y will be removed in the next release, so consider upgrading ZooKeeper. For information about how to upgrade ZooKeeper, see the ZooKeeper documentation.

FAQ

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

Never fear! If you occasionally merged upstream/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

  2. Checkout a new branch with the original name feature-xxx from upstream. This branch will supersede our old one.

    git checkout -b feature-xxx upstream/master

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

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

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