Apache Druid is a community-led project. We are delighted to receive contributions to the docs ranging from minor fixes to big new features.
Druid docs contributors:
Druid docs contributors can open an issue about documentation, or contribute a change with a pull request (PR).
The open source Druid docs are located here: https://druid.apache.org/docs/latest/design/index.html
If you need to update a Druid doc, locate and update the doc in the Druid repo following the instructions below.
The Druid team works on the master
branch and then branches for a release, such as 26.0.0
.
See CONTRIBUTING.md
for instructions on contributing to Apache Druid.
Before you can contribute to the Druid docs for the first time, you must complete the following steps:
Fork the Druid repo. Your fork will be the origin
remote.
Clone your fork:
git clone git@github.com:GITHUB_USERNAME/druid.git
Replace GITHUB_USERNAME
with your GitHub username.
In the directory where you cloned your fork, set up apache/druid
as your your remote upstream
repo:
git remote add upstream https://github.com/apache/druid.git
Confirm that your fork shows up as the origin repo and apache/druid
shows up as the upstream repo:
git remote -v
Verify that you have your email configured for GitHub:
git config user.email
If you need to set your email, see the GitHub instructions.
Install Docusaurus so that you can build the site locally. Run either npm install
or yarn install
in the website
directory.
Before you contribute, make sure your local branch of master
and the upstream Apache branch are up-to-date and in sync. This can help you avoid merge conflicts. Run the following commands on your fork's master
branch:
git fetch origin
git fetch upstream
Then run either one of the following commands:
git rebase upstream/master # or git merge upstream/master
Now you're up to date, and you can make your changes.
Create your working branch:
git checkout -b MY-BRANCH
Provide a name for your feature branch in MY-BRANCH
.
Find the file that you want to make changes to. All the source files for the docs are written in Markdown and located in the docs
directory. The URL for the page includes the subdirectory the source file is in. For example, the SQL-based ingestion tutorial found at https://druid.apache.org/docs/latest/tutorials/tutorial-msq-extern.html
is in the tutorials
subdirectory.
If you‘re adding a page, create a new Markdown file in the appropriate subdirectory. Then, copy the front matter and Apache license from an existing file. Update the title
and id
fields. Don’t forget to add it to website/sidebars.json
so that your new page shows up in the navigation.
Test changes locally by building the site and navigating to your changes. In the website
directory, run docusaurus-start
. By default, this starts the site on localhost:3000
. If port 3000
is already in use, it'll increment the port number from there.
Use the following commands to run the link and spellcheckers locally:
cd website # You only need to install once npm install npm run build npm run spellcheck npm run link-lint
This step can save you time during the review process since they'll run faster than the GitHub Action version of the checks and warn you of issues before you create a PR.
Push your changes to your fork:
git push --set-upstream origin MY-BRANCH
Go to the Druid repo. GitHub should recognize that you have a new branch in your fork. Create a pull request from your Druid fork and branch to the master
branch in the Apache Druid repo.
The pull request template is extensive. You may not need all the information there, so feel free to delete unneeded sections as you fill it out. Once you create the pull request, GitHub automatically labels the issue so that reviewers can take a look.
The docs go through a review process similar to the code where community members will offer feedback. Once the review process is complete and your changes are merged, they'll be available on the live site when the site gets republished.
Consistent style, formatting, and tone make documentation easier to consume. For the majority of style considerations, the Apache Druid documentation follows the Google Developer Documentation Style Guide. The style guide should serve as a point of reference to enable contributors and reviewers to maintain documentation quality.
In some cases, Google Style might make the Druid docs more difficult to read and understand. This section highlights those exceptions.
For SQL keywords and functions, use all caps, but do not use code font.
:::tip
Correct
The UNNEST clause unnests array values.
Incorrect
The `UNNEST` clause unnests array values. :::
For optional parameters and arguments, enclose the optional parameter and leading command in brackets.
:::tip
Correct
HUMAN_READABLE_BINARY_BYTE_FORMAT(value[, precision])
Incorrect
HUMAN_READABLE_BINARY_BYTE_FORMAT(value, [precision]) :::
When editing or adding tables, do not include extra characters to “prettify” the table format within the Markdown source. Some code editors may format tables by default. See the developer style guide for more information.
:::tip
Correct
| Column 1 | Column 2 | Column 3 | | --- | --- | --- | | value 1 | val 2 | a-very-long-value 3 |
Incorrect
| Column 1 | Column 2 | Column 3 | | -------- | -------- | ------------------- | | value 1 | val 2 | a-very-long-value 3 |
:::
Before publishing new content or updating an existing topic, you can audit your documentation using the following checklist to make sure your contributions align with existing documentation:
-ing
. For example, don't use “Configuring Druid.” Use “Configure Druid.”