"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[4835],{3905:(e,t,n)=>{n.d(t,{Zo:()=>u,kt:()=>h});var a=n(67294);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);t&&(a=a.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,a)}return n}function i(e){for(var t=1;t<arguments.length;t++){var n=null!=arguments[t]?arguments[t]:{};t%2?o(Object(n),!0).forEach((function(t){r(e,t,n[t])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(n)):o(Object(n)).forEach((function(t){Object.defineProperty(e,t,Object.getOwnPropertyDescriptor(n,t))}))}return e}function l(e,t){if(null==e)return{};var n,a,r=function(e,t){if(null==e)return{};var n,a,r={},o=Object.keys(e);for(a=0;a<o.length;a++)n=o[a],t.indexOf(n)>=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(a=0;a<o.length;a++)n=o[a],t.indexOf(n)>=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var s=a.createContext({}),p=function(e){var t=a.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},u=function(e){var t=p(e.components);return a.createElement(s.Provider,{value:t},e.children)},d="mdxType",c={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},m=a.forwardRef((function(e,t){var n=e.components,r=e.mdxType,o=e.originalType,s=e.parentName,u=l(e,["components","mdxType","originalType","parentName"]),d=p(n),m=r,h=d["".concat(s,".").concat(m)]||d[m]||c[m]||o;return n?a.createElement(h,i(i({ref:t},u),{},{components:n})):a.createElement(h,i({ref:t},u))}));function h(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var o=n.length,i=new Array(o);i[0]=m;var l={};for(var s in t)hasOwnProperty.call(t,s)&&(l[s]=t[s]);l.originalType=e,l[d]="string"==typeof e?e:r,i[1]=l;for(var p=2;p<o;p++)i[p]=n[p];return a.createElement.apply(null,i)}return a.createElement.apply(null,n)}m.displayName="MDXCreateElement"},84281:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>u,contentTitle:()=>s,default:()=>h,frontMatter:()=>l,metadata:()=>p,toc:()=>d});var a=n(87462),r=n(63366),o=(n(67294),n(3905)),i=["components"],l={id:"contribute-to-docs",title:"Contribute to Druid docs"},s=void 0,p={unversionedId:"development/contribute-to-docs",id:"development/contribute-to-docs",title:"Contribute to Druid docs",description:"\x3c!--",source:"@site/docs/29.0.1/development/docs-contribute.md",sourceDirName:"development",slug:"/development/contribute-to-docs",permalink:"/docs/29.0.1/development/contribute-to-docs",draft:!1,tags:[],version:"current",frontMatter:{id:"contribute-to-docs",title:"Contribute to Druid docs"},sidebar:"docs",previous:{title:"Versioning",permalink:"/docs/29.0.1/development/versioning"},next:{title:"Experimental features",permalink:"/docs/29.0.1/development/experimental"}},u={},d=[{value:"Getting started",id:"getting-started",level:2},{value:"Druid repo branches",id:"druid-repo-branches",level:2},{value:"Before you begin",id:"before-you-begin",level:2},{value:"Contributing",id:"contributing",level:2},{value:"Style guide",id:"style-guide",level:2},{value:"Notable style exceptions",id:"notable-style-exceptions",level:3},{value:"SQL keyword syntax",id:"sql-keyword-syntax",level:4},{value:"Optional parameters and arguments",id:"optional-parameters-and-arguments",level:4},{value:"Markdown table format",id:"markdown-table-format",level:4},{value:"Style checklist",id:"style-checklist",level:3}],c={toc:d},m="wrapper";function h(e){var t=e.components,n=(0,r.Z)(e,i);return(0,o.kt)(m,(0,a.Z)({},c,n,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("p",null,"Apache Druid is a ",(0,o.kt)("a",{parentName:"p",href:"https://druid.apache.org/community/"},"community-led project"),". We are delighted to receive contributions to the docs ranging from minor fixes to big new features."),(0,o.kt)("p",null,"Druid docs contributors:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},"Improve existing content"),(0,o.kt)("li",{parentName:"ul"},"Create new content")),(0,o.kt)("h2",{id:"getting-started"},"Getting started"),(0,o.kt)("p",null,"Druid docs contributors can open an issue about documentation, or contribute a change with a pull request (PR)."),(0,o.kt)("p",null,"The open source Druid docs are located here:\n",(0,o.kt)("a",{parentName:"p",href:"https://druid.apache.org/docs/latest/design/index.html"},"https://druid.apache.org/docs/latest/design/index.html")),(0,o.kt)("p",null,"If you need to update a Druid doc, locate and update the doc in the Druid repo following the instructions below."),(0,o.kt)("h2",{id:"druid-repo-branches"},"Druid repo branches"),(0,o.kt)("p",null,"The Druid team works on the ",(0,o.kt)("inlineCode",{parentName:"p"},"master")," branch and then branches for a release, such as ",(0,o.kt)("inlineCode",{parentName:"p"},"26.0.0"),"."),(0,o.kt)("p",null,"See ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/apache/incubator-druid/blob/master/CONTRIBUTING.md"},(0,o.kt)("inlineCode",{parentName:"a"},"CONTRIBUTING.md"))," for instructions on contributing to Apache Druid."),(0,o.kt)("h2",{id:"before-you-begin"},"Before you begin"),(0,o.kt)("p",null,"Before you can contribute to the Druid docs for the first time, you must complete the following steps:"),(0,o.kt)("ol",null,(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Fork the ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/apache/druid"},"Druid repo"),". Your fork will be the ",(0,o.kt)("inlineCode",{parentName:"p"},"origin")," remote.")),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Clone your fork: "),(0,o.kt)("pre",{parentName:"li"},(0,o.kt)("code",{parentName:"pre",className:"language-bash"},"git clone git@github.com:GITHUB_USERNAME/druid.git\n")),(0,o.kt)("p",{parentName:"li"},"Replace ",(0,o.kt)("inlineCode",{parentName:"p"},"GITHUB_USERNAME")," with your GitHub username.")),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"In the directory where you cloned your fork, set up ",(0,o.kt)("inlineCode",{parentName:"p"},"apache/druid"),"  as your your remote ",(0,o.kt)("inlineCode",{parentName:"p"},"upstream")," repo:"),(0,o.kt)("pre",{parentName:"li"},(0,o.kt)("code",{parentName:"pre",className:"language-bash"},"git remote add upstream https://github.com/apache/druid.git\n"))),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Confirm that your fork shows up as the origin repo and ",(0,o.kt)("inlineCode",{parentName:"p"},"apache/druid")," shows up as the upstream repo:   "),(0,o.kt)("pre",{parentName:"li"},(0,o.kt)("code",{parentName:"pre",className:"language-bash"},"git remote -v\n"))),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Verify that you have your email configured for GitHub:"),(0,o.kt)("pre",{parentName:"li"},(0,o.kt)("code",{parentName:"pre",className:"language-bash"},"git config user.email\n")),(0,o.kt)("p",{parentName:"li"},"If you need to set your email, see the ",(0,o.kt)("a",{parentName:"p",href:"https://docs.github.com/en/github-ae@latest/account-and-profile/setting-up-and-managing-your-github-user-account/managing-email-preferences/setting-your-commit-email-address#setting-your-commit-email-address-in-git"},"GitHub instructions"),".")),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Install Docusaurus so that you can build the site locally. Run either ",(0,o.kt)("inlineCode",{parentName:"p"},"npm install")," or ",(0,o.kt)("inlineCode",{parentName:"p"},"yarn install")," in the ",(0,o.kt)("inlineCode",{parentName:"p"},"website")," directory."))),(0,o.kt)("h2",{id:"contributing"},"Contributing"),(0,o.kt)("p",null,"Before you contribute, make sure your local branch of ",(0,o.kt)("inlineCode",{parentName:"p"},"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 ",(0,o.kt)("inlineCode",{parentName:"p"},"master")," branch:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-bash"},"git fetch origin\ngit fetch upstream\n")),(0,o.kt)("p",null,"Then run either one of the following commands:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-bash"},"git rebase upstream/master\n# or\ngit merge upstream/master\n")),(0,o.kt)("p",null,"Now you're up to date, and you can make your changes."),(0,o.kt)("ol",null,(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Create your working branch:"),(0,o.kt)("pre",{parentName:"li"},(0,o.kt)("code",{parentName:"pre",className:"language-bash"},"git checkout -b MY-BRANCH\n")),(0,o.kt)("p",{parentName:"li"},"Provide a name for your feature branch in ",(0,o.kt)("inlineCode",{parentName:"p"},"MY-BRANCH"),".")),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"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 ",(0,o.kt)("inlineCode",{parentName:"p"},"docs")," directory. The URL for the page includes the subdirectory the source file is in. For example, the SQL-based ingestion tutorial found at ",(0,o.kt)("inlineCode",{parentName:"p"},"https://druid.apache.org/docs/latest/tutorials/tutorial-msq-extern.html")," is in the ",(0,o.kt)("inlineCode",{parentName:"p"},"tutorials")," subdirectory."),(0,o.kt)("p",{parentName:"li"},"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 ",(0,o.kt)("inlineCode",{parentName:"p"},"title")," and ",(0,o.kt)("inlineCode",{parentName:"p"},"id")," fields. Don't forget to add it to ",(0,o.kt)("inlineCode",{parentName:"p"},"website/sidebars.json")," so that your new page shows up in the navigation.")),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Test changes locally by building the site and navigating to your changes. In the ",(0,o.kt)("inlineCode",{parentName:"p"},"website")," directory, run ",(0,o.kt)("inlineCode",{parentName:"p"},"docusaurus-start"),". By default, this starts the site on ",(0,o.kt)("inlineCode",{parentName:"p"},"localhost:3000"),". If port ",(0,o.kt)("inlineCode",{parentName:"p"},"3000")," is already in use, it'll increment the port number from there.")),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Use the following commands to run the link and spellcheckers locally: "),(0,o.kt)("pre",{parentName:"li"},(0,o.kt)("code",{parentName:"pre",className:"language-bash"},"cd website\n# You only need to install once\nnpm install\nnpm run build\n\nnpm run spellcheck\nnpm run link-lint\n")),(0,o.kt)("p",{parentName:"li"},"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.")),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Push your changes to your fork: "),(0,o.kt)("pre",{parentName:"li"},(0,o.kt)("code",{parentName:"pre",className:"language-bash"},"git push --set-upstream origin MY-BRANCH\n"))),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"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 ",(0,o.kt)("inlineCode",{parentName:"p"},"master")," branch in the Apache Druid repo."))),(0,o.kt)("p",null,"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."),(0,o.kt)("p",null,"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. "),(0,o.kt)("h2",{id:"style-guide"},"Style guide"),(0,o.kt)("p",null,"Consistent style, formatting, and tone make documentation easier to consume.\nFor the majority of style considerations, the Apache Druid documentation follows the ",(0,o.kt)("a",{parentName:"p",href:"https://developers.google.com/style"},"Google Developer Documentation Style Guide"),".\nThe style guide should serve as a point of reference to enable contributors and reviewers to maintain documentation quality."),(0,o.kt)("h3",{id:"notable-style-exceptions"},"Notable style exceptions"),(0,o.kt)("p",null,"In some cases, Google Style might make the Druid docs more difficult to read and understand. This section highlights those exceptions."),(0,o.kt)("h4",{id:"sql-keyword-syntax"},"SQL keyword syntax"),(0,o.kt)("p",null,"For SQL keywords and functions, use all caps, but do not use code font."),(0,o.kt)("admonition",{type:"tip"},(0,o.kt)("p",{parentName:"admonition"},(0,o.kt)("strong",{parentName:"p"},"Correct")),(0,o.kt)("p",{parentName:"admonition"},"The UNNEST clause unnests array values."),(0,o.kt)("p",{parentName:"admonition"},(0,o.kt)("strong",{parentName:"p"},"Incorrect")),(0,o.kt)("p",{parentName:"admonition"},"The ","`","UNNEST","`"," clause unnests array values.")),(0,o.kt)("h4",{id:"optional-parameters-and-arguments"},"Optional parameters and arguments"),(0,o.kt)("p",null,"For optional parameters and arguments, enclose the optional parameter and leading command in brackets."),(0,o.kt)("admonition",{type:"tip"},(0,o.kt)("p",{parentName:"admonition"},(0,o.kt)("strong",{parentName:"p"},"Correct")),(0,o.kt)("p",{parentName:"admonition"},"HUMAN_READABLE_BINARY_BYTE_FORMAT(value","[, precision]",")"),(0,o.kt)("p",{parentName:"admonition"},(0,o.kt)("strong",{parentName:"p"},"Incorrect")),(0,o.kt)("p",{parentName:"admonition"},"HUMAN_READABLE_BINARY_BYTE_FORMAT(value, ","[","precision])")),(0,o.kt)("h4",{id:"markdown-table-format"},"Markdown table format"),(0,o.kt)("p",null,'When editing or adding tables, do not include extra characters to "prettify" the table format within the Markdown source.\nSome code editors may format tables by default.\nSee the developer ',(0,o.kt)("a",{parentName:"p",href:"https://github.com/apache/druid/blob/master/dev/style-conventions.md"},"style guide")," for more information."),(0,o.kt)("admonition",{type:"tip"},(0,o.kt)("p",{parentName:"admonition"},(0,o.kt)("strong",{parentName:"p"},"Correct")),(0,o.kt)("pre",{parentName:"admonition"},(0,o.kt)("code",{parentName:"pre",className:"language-markdown"},"| Column 1 | Column 2 | Column 3 |\n| --- | --- | --- |\n| value 1 | val 2 | a-very-long-value 3 |\n")),(0,o.kt)("p",{parentName:"admonition"},(0,o.kt)("strong",{parentName:"p"},"Incorrect")),(0,o.kt)("pre",{parentName:"admonition"},(0,o.kt)("code",{parentName:"pre",className:"language-markdown"},"| Column 1 | Column 2 | Column 3            |\n| -------- | -------- | ------------------- |\n| value 1  | val 2    | a-very-long-value 3 |\n"))),(0,o.kt)("h3",{id:"style-checklist"},"Style checklist"),(0,o.kt)("p",null,"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:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},"Use descriptive link text. If a link downloads a file, make sure to indicate this action."),(0,o.kt)("li",{parentName:"ul"},"Use present tense where possible."),(0,o.kt)("li",{parentName:"ul"},"Avoid negative constructions when possible. In other words, try to tell people what they should do instead of what they shouldn't."),(0,o.kt)("li",{parentName:"ul"},"Use clear and direct language."),(0,o.kt)("li",{parentName:"ul"},"Use descriptive headings and titles."),(0,o.kt)("li",{parentName:"ul"},"Avoid using a present participle or gerund as the first word in a heading or title. A shortcut for this is to not start with a word that ends in ",(0,o.kt)("inlineCode",{parentName:"li"},"-ing"),'. For example, don\'t use "Configuring Druid." Use "Configure Druid."'),(0,o.kt)("li",{parentName:"ul"},"Use sentence case in document titles and headings."),(0,o.kt)("li",{parentName:"ul"},"Don\u2019t use images of text or code samples."),(0,o.kt)("li",{parentName:"ul"},"Use SVG over PNG for images if you can."),(0,o.kt)("li",{parentName:"ul"},"Provide alt text or an equivalent text explanation with each image."),(0,o.kt)("li",{parentName:"ul"},"Use the appropriate text-formatting. For example, make sure code snippets and property names are in code font and UI elements are bold. Generally, you should  avoid using bold or italics to emphasize certain words unless there's a good reason."),(0,o.kt)("li",{parentName:"ul"},'Put conditional clauses before instructions. In the following example, "to drop a segment" is the conditional clause: to drop a segment, do the following.'),(0,o.kt)("li",{parentName:"ul"},'Avoid gender-specific pronouns, instead use "they."'),(0,o.kt)("li",{parentName:"ul"},'Use second person singular \u2014 "you" instead of "we."'),(0,o.kt)("li",{parentName:"ul"},'When American spelling is different from Commonwealth/"British" spelling, use the American spelling.'),(0,o.kt)("li",{parentName:"ul"},"Don\u2019t use terms considered disrespectful. Refer to a list like Google\u2019s ",(0,o.kt)("a",{parentName:"li",href:"https://developers.google.com/style/word-list"},"Word list")," for guidance and alternatives."),(0,o.kt)("li",{parentName:"ul"},"Use straight quotation marks and straight apostrophes instead of the curly versions."),(0,o.kt)("li",{parentName:"ul"},"Introduce a list, a table, or a procedure with an introductory sentence that prepares the reader for what they're about to read.")))}h.isMDXComponent=!0}}]);