| (window.webpackJsonp=window.webpackJsonp||[]).push([[44],{111:function(e,t,a){"use strict";a.r(t),a.d(t,"frontMatter",(function(){return o})),a.d(t,"metadata",(function(){return c})),a.d(t,"toc",(function(){return l})),a.d(t,"default",(function(){return s}));var r=a(3),i=a(7),n=(a(0),a(193)),o={title:"How To Contribute to Submarine"},c={unversionedId:"community/contributing",id:"community/contributing",isDocsHomePage:!1,title:"How To Contribute to Submarine",description:"\x3c!--",source:"@site/docs/community/contributing.md",slug:"/community/contributing",permalink:"/docs/next/community/contributing",editUrl:"https://github.com/apache/submarine/edit/master/website/docs/community/contributing.md",version:"current",sidebar:"docs",previous:{title:"Guide for Apache Submarine Committers",permalink:"/docs/next/community/HowToCommit"},next:{title:"How to vote a Committer or PMC",permalink:"/docs/next/community/HowToVoteCommitterOrPMC"}},l=[{value:"Preface",id:"preface",children:[]},{value:"Build Submarine",id:"build-submarine",children:[]},{value:"Creating patches",id:"creating-patches",children:[{value:"Step1: Fork apache/submarine github repository (first time)",id:"step1-fork-apachesubmarine-github-repository-first-time",children:[]},{value:"Step2: Clone the Submarine to your local machine",id:"step2-clone-the-submarine-to-your-local-machine",children:[]},{value:"Step3: Create a new Jira in Submarine project",id:"step3-create-a-new-jira-in-submarine-project",children:[]},{value:"Step4: Create a local branch for your contribution",id:"step4-create-a-local-branch-for-your-contribution",children:[]},{value:"Step5: Develop & Create commits",id:"step5-develop--create-commits",children:[]},{value:"Step6: Syncing your local branch with upstream/master",id:"step6-syncing-your-local-branch-with-upstreammaster",children:[]},{value:"Step7: Push your local branch to your personal fork",id:"step7-push-your-local-branch-to-your-personal-fork",children:[]},{value:"Step8: Check GitHub Actions status of your personal commit",id:"step8-check-github-actions-status-of-your-personal-commit",children:[]},{value:"Step9: Create a pull request on github UI",id:"step9-create-a-pull-request-on-github-ui",children:[]},{value:"Step10: Check GitHub Actions status of your pull request in apache/submarine",id:"step10-check-github-actions-status-of-your-pull-request-in-apachesubmarine",children:[]},{value:"Step11: The Review Process",id:"step11-the-review-process",children:[]},{value:"Step12: Address review comments",id:"step12-address-review-comments",children:[]},{value:"Code convention",id:"code-convention",children:[]}]}],u={toc:l};function s(e){var t=e.components,o=Object(i.a)(e,["components"]);return Object(n.b)("wrapper",Object(r.a)({},u,o,{components:t,mdxType:"MDXLayout"}),Object(n.b)("p",null,"There are several ways to contribute to Submarine:"),Object(n.b)("ol",null,Object(n.b)("li",{parentName:"ol"},"Develop and Commit source code (This document will primarily focus on this.)"),Object(n.b)("li",{parentName:"ol"},"Report issues (You can report issues with both Github or Jira.)"),Object(n.b)("li",{parentName:"ol"},"Discuss/Answer questions on the mailing list"),Object(n.b)("li",{parentName:"ol"},"Share use cases")),Object(n.b)("h2",{id:"preface"},"Preface"),Object(n.b)("ul",null,Object(n.b)("li",{parentName:"ul"},Object(n.b)("strong",{parentName:"li"},"Apache Submarine")," is an ",Object(n.b)("a",{parentName:"li",href:"https://github.com/apache/submarine/blob/master/LICENSE"},"Apache 2.0 License")," Software. Contributing to Submarine means you agree to the Apache 2.0 License. "),Object(n.b)("li",{parentName:"ul"},"Please read ",Object(n.b)("a",{parentName:"li",href:"http://www.apache.org/foundation/policies/conduct.html"},"Code of Conduct")," carefully."),Object(n.b)("li",{parentName:"ul"},"The document ",Object(n.b)("a",{parentName:"li",href:"http://www.apache.org/foundation/how-it-works.html"},"How It Works")," can help you understand Apache Software Foundation further.")),Object(n.b)("h2",{id:"build-submarine"},"Build Submarine"),Object(n.b)("ul",null,Object(n.b)("li",{parentName:"ul"},Object(n.b)("a",{parentName:"li",href:"/docs/next/devDocs/BuildFromCode"},"Build From Code"))),Object(n.b)("h2",{id:"creating-patches"},"Creating patches"),Object(n.b)("p",null,"Submarine follows ",Object(n.b)("a",{parentName:"p",href:"https://github.com/sevntu-checkstyle/sevntu.checkstyle/wiki/Development-workflow-with-Git:-Fork,-Branching,-Commits,-and-Pull-Request"},"Fork & Pull")," model."),Object(n.b)("h3",{id:"step1-fork-apachesubmarine-github-repository-first-time"},"Step1: Fork apache/submarine github repository (first time)"),Object(n.b)("ul",null,Object(n.b)("li",{parentName:"ul"},"Visit ",Object(n.b)("a",{parentName:"li",href:"https://github.com/apache/submarine"},"https://github.com/apache/submarine")),Object(n.b)("li",{parentName:"ul"},"Click the ",Object(n.b)("inlineCode",{parentName:"li"},"Fork")," button to create a fork of the repository")),Object(n.b)("h3",{id:"step2-clone-the-submarine-to-your-local-machine"},"Step2: Clone the Submarine to your local machine"),Object(n.b)("pre",null,Object(n.b)("code",{parentName:"pre",className:"language-sh"},"# USERNAME \u2013 your Github user account name.\ngit clone git@github.com:${USERNAME}/submarine.git\n# or: git clone https://github.com/${USERNAME}/submarine.git \n \ncd submarine\n# set upstream \ngit remote add upstream git@github.com:apache/submarine.git\n# or: git remote add upstream https://github.com/apache/submarine.git\n\n# Don't push to the upstream master.\ngit remote set-url --push upstream no_push\n\n# Check upstream/origin:\n# origin git@github.com:${USERNAME}/submarine.git (fetch)\n# origin git@github.com:${USERNAME}/submarine.git (push)\n# upstream git@github.com:apache/submarine.git (fetch)\n# upstream no_push (push)\ngit remote -v\n")),Object(n.b)("h3",{id:"step3-create-a-new-jira-in-submarine-project"},"Step3: Create a new Jira in Submarine project"),Object(n.b)("ul",null,Object(n.b)("li",{parentName:"ul"},"New contributors need privilege to create JIRA issues. Please email ",Object(n.b)("a",{parentName:"li",href:"mailto:kaihsun@apache.org"},"kaihsun@apache.org"),' with your Jira username. In addition, the email title should be "',"[New Submarine Contributor]",'".'),Object(n.b)("li",{parentName:"ul"},"Check ",Object(n.b)("a",{parentName:"li",href:"https://issues.apache.org/jira/projects/SUBMARINE/issues/SUBMARINE-748?filter=allopenissues"},"Jira issue tracker")," for existing issues."),Object(n.b)("li",{parentName:"ul"},"Create a new Jira issue in Submarine project. When the issue is created, a Jira number (eg. SUBMARINE-748) will be assigned to the issue automatically.\n",Object(n.b)("img",{alt:"jira_number_example",src:a(225).default}))),Object(n.b)("h3",{id:"step4-create-a-local-branch-for-your-contribution"},"Step4: Create a local branch for your contribution"),Object(n.b)("pre",null,Object(n.b)("code",{parentName:"pre",className:"language-sh"},"cd submarine\n\n# Make your local master up-to-date\ngit checkout master\ngit fetch upstream \ngit rebase upstream/master\n\n# Create a new branch fro issue SUBMARINE-${jira_number}\ngit checkout -b SUBMARINE-${jira_number}\n\n# Example: git checkout -b SUBMARINE-748 \n")),Object(n.b)("h3",{id:"step5-develop--create-commits"},"Step5: Develop & Create commits"),Object(n.b)("ul",null,Object(n.b)("li",{parentName:"ul"},"You can edit the code on the ",Object(n.b)("inlineCode",{parentName:"li"},"SUBMARINE-${jira_number}")," branch. (Coding Style: ",Object(n.b)("a",{parentName:"li",href:"#code-convention"},"Code Convention"),")"),Object(n.b)("li",{parentName:"ul"},"Create commits")),Object(n.b)("pre",null,Object(n.b)("code",{parentName:"pre",className:"language-sh"},'git add ${edited files}\ngit commit -m "SUBMARINE-${jira_number}. ${Commit Message}"\n# Example: git commit -m "SUBMARINE-748. Update Contributing guide" \n')),Object(n.b)("h3",{id:"step6-syncing-your-local-branch-with-upstreammaster"},"Step6: Syncing your local branch with upstream/master"),Object(n.b)("pre",null,Object(n.b)("code",{parentName:"pre",className:"language-sh"},"# On SUBMARINE-${jira_number} branch\ngit fetch upstream\ngit rebase upstream/master\n")),Object(n.b)("ul",null,Object(n.b)("li",{parentName:"ul"},"Please do not use ",Object(n.b)("inlineCode",{parentName:"li"},"git pull")," to synchronize your local branch. Because ",Object(n.b)("inlineCode",{parentName:"li"},"git pull")," does a merge to create merged commits, these will make commit history messy.")),Object(n.b)("h3",{id:"step7-push-your-local-branch-to-your-personal-fork"},"Step7: Push your local branch to your personal fork"),Object(n.b)("pre",null,Object(n.b)("code",{parentName:"pre",className:"language-sh"},"git push origin SUBMARINE-${jira_number} \n")),Object(n.b)("h3",{id:"step8-check-github-actions-status-of-your-personal-commit"},"Step8: Check GitHub Actions status of your personal commit"),Object(n.b)("ul",null,Object(n.b)("li",{parentName:"ul"},"Visit ",Object(n.b)("inlineCode",{parentName:"li"},"https://github.com/${USERNAME}/submarine/actions")),Object(n.b)("li",{parentName:"ul"},"Please make sure your new commits can pass all workflows before creating a pull request.")),Object(n.b)("p",null,Object(n.b)("img",{alt:"check_ci_pass",src:a(226).default})),Object(n.b)("h3",{id:"step9-create-a-pull-request-on-github-ui"},"Step9: Create a pull request on github UI"),Object(n.b)("ul",null,Object(n.b)("li",{parentName:"ul"},"Visit your fork at ",Object(n.b)("inlineCode",{parentName:"li"},"https://github.com/${USERNAME}/submarine.git")),Object(n.b)("li",{parentName:"ul"},"Click ",Object(n.b)("inlineCode",{parentName:"li"},"Compare & Pull Request")," button to create pull request.\n",Object(n.b)("img",{alt:"compare_pull_request_button",src:a(227).default}))),Object(n.b)("h4",{id:"pull-request-template"},"Pull Request template"),Object(n.b)("ul",null,Object(n.b)("li",{parentName:"ul"},Object(n.b)("a",{parentName:"li",href:"https://github.com/apache/submarine/blob/bd7578cc28f8280f9170938d4469fcc965e24a89/.github/PULL_REQUEST_TEMPLATE"},"Pull request template")),Object(n.b)("li",{parentName:"ul"},"Filling the template thoroughly can improve the speed of the review process. Example: ")),Object(n.b)("p",null,Object(n.b)("img",{alt:"pull_request_template_example",src:a(228).default})),Object(n.b)("h3",{id:"step10-check-github-actions-status-of-your-pull-request-in-apachesubmarine"},"Step10: Check GitHub Actions status of your pull request in apache/submarine"),Object(n.b)("ul",null,Object(n.b)("li",{parentName:"ul"},"Visit ",Object(n.b)("a",{parentName:"li",href:"https://github.com/apache/submarine/actions"},"https://github.com/apache/submarine/actions")),Object(n.b)("li",{parentName:"ul"},"Please make sure your pull request can pass all workflows. ")),Object(n.b)("h3",{id:"step11-the-review-process"},"Step11: The Review Process"),Object(n.b)("ul",null,Object(n.b)("li",{parentName:"ul"},"Anyone can be a reviewer and comment on the pull requests."),Object(n.b)("li",{parentName:"ul"},'Reviewer can indicate that a patch looks suitable for merging with a comment such as: "Looks good", "LGTM", "+1". (PS: LGTM = Looks Good To Me)'),Object(n.b)("li",{parentName:"ul"},'At least one indication of suitability (e.g. "LGTM") from a committer is required to be merged. '),Object(n.b)("li",{parentName:"ul"},'A committer can then initiate lazy consensus ("Merge if there is no more discussion") after which the code can be merged after a particular time (usually 24 hours) if there are no more reviews.'),Object(n.b)("li",{parentName:"ul"},"Contributors can ping reviewers (including committers) by commenting 'Ready to review'.")),Object(n.b)("h3",{id:"step12-address-review-comments"},"Step12: Address review comments"),Object(n.b)("ul",null,Object(n.b)("li",{parentName:"ul"},"Push new commits to SUBMARINE-${jira_number} branch. The pull request will update automatically."),Object(n.b)("li",{parentName:"ul"},"After you address all review comments, committers will merge the pull request.")),Object(n.b)("h3",{id:"code-convention"},"Code convention"),Object(n.b)("p",null,"We are following Google Code style:"),Object(n.b)("ul",null,Object(n.b)("li",{parentName:"ul"},Object(n.b)("a",{parentName:"li",href:"https://google.github.io/styleguide/javaguide.html"},"Java style")),Object(n.b)("li",{parentName:"ul"},Object(n.b)("a",{parentName:"li",href:"https://google.github.io/styleguide/shell.xml"},"Shell style"))),Object(n.b)("p",null,"There are some plugins to format, lint your code in IDE (use ",Object(n.b)("a",{parentName:"p",href:"hhttps://github.com/apache/submarine/blob/master/dev-support/maven-config/checkstyle.xml"},"dev-support/maven-config/checkstyle.xml")," as rules)"),Object(n.b)("ul",null,Object(n.b)("li",{parentName:"ul"},Object(n.b)("a",{parentName:"li",href:"https://plugins.jetbrains.com/plugin/1065"},"Checkstyle plugin for Intellij")," (",Object(n.b)("a",{parentName:"li",href:"http://stackoverflow.com/questions/26955766/intellij-idea-checkstyle"},"Setting Guide"),")"),Object(n.b)("li",{parentName:"ul"},Object(n.b)("a",{parentName:"li",href:"http://eclipse-cs.sourceforge.net/#!/"},"Checkstyle plugin for Eclipse")," (",Object(n.b)("a",{parentName:"li",href:"http://eclipse-cs.sourceforge.net/#!/project-setup"},"Setting Guide"),")")))}s.isMDXComponent=!0},193:function(e,t,a){"use strict";a.d(t,"a",(function(){return b})),a.d(t,"b",(function(){return h}));var r=a(0),i=a.n(r);function n(e,t,a){return t in e?Object.defineProperty(e,t,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[t]=a,e}function o(e,t){var a=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);t&&(r=r.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),a.push.apply(a,r)}return a}function c(e){for(var t=1;t<arguments.length;t++){var a=null!=arguments[t]?arguments[t]:{};t%2?o(Object(a),!0).forEach((function(t){n(e,t,a[t])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(a)):o(Object(a)).forEach((function(t){Object.defineProperty(e,t,Object.getOwnPropertyDescriptor(a,t))}))}return e}function l(e,t){if(null==e)return{};var a,r,i=function(e,t){if(null==e)return{};var a,r,i={},n=Object.keys(e);for(r=0;r<n.length;r++)a=n[r],t.indexOf(a)>=0||(i[a]=e[a]);return i}(e,t);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);for(r=0;r<n.length;r++)a=n[r],t.indexOf(a)>=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(i[a]=e[a])}return i}var u=i.a.createContext({}),s=function(e){var t=i.a.useContext(u),a=t;return e&&(a="function"==typeof e?e(t):c(c({},t),e)),a},b=function(e){var t=s(e.components);return i.a.createElement(u.Provider,{value:t},e.children)},p={inlineCode:"code",wrapper:function(e){var t=e.children;return i.a.createElement(i.a.Fragment,{},t)}},m=i.a.forwardRef((function(e,t){var a=e.components,r=e.mdxType,n=e.originalType,o=e.parentName,u=l(e,["components","mdxType","originalType","parentName"]),b=s(a),m=r,h=b["".concat(o,".").concat(m)]||b[m]||p[m]||n;return a?i.a.createElement(h,c(c({ref:t},u),{},{components:a})):i.a.createElement(h,c({ref:t},u))}));function h(e,t){var a=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var n=a.length,o=new Array(n);o[0]=m;var c={};for(var l in t)hasOwnProperty.call(t,l)&&(c[l]=t[l]);c.originalType=e,c.mdxType="string"==typeof e?e:r,o[1]=c;for(var u=2;u<n;u++)o[u]=a[u];return i.a.createElement.apply(null,o)}return i.a.createElement.apply(null,a)}m.displayName="MDXCreateElement"},225:function(e,t,a){"use strict";a.r(t),t.default=a.p+"assets/images/jira_number_example-9d86e8dd3b72d9d9c2adddfbffc00a54.png"},226:function(e,t,a){"use strict";a.r(t),t.default=a.p+"assets/images/check_ci_pass-9c6656dec7130470506c7420e55c7dd0.png"},227:function(e,t,a){"use strict";a.r(t),t.default=a.p+"assets/images/compare_pull_request_button-a5c8f7a7ebda5fad45d1d9e6ca8ed58a.png"},228:function(e,t,a){"use strict";a.r(t),t.default=a.p+"assets/images/pull_request_template_example-5db7207e23fa54cca6de32325e8d7c67.png"}}]); |