https://headlamp.dev/assets/js/f14b9492.fcb1dde5.js

1"use strict";(self.webpackChunkheadlamp_website=self.webpackChunkheadlamp_website||[]).push([[19440],{28453:(e,n,i)=>{i.d(n,{R:()=>r,x:()=>l});var s=i(96540);const t={},o=s.createContext(t);function r(e){const n=s.useContext(o);return s.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function l(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:r(e.components),s.createElement(o.Provider,{value:n},e.children)}},47629:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>a,contentTitle:()=>r,default:()=>h,frontMatter:()=>o,metadata:()=>l,toc:()=>d});var s=i(74848),t=i(28453);const o={title:"Contribution Guidelines",sidebar_label:"Contributing",sidebar_position:4},r=void 0,l={id:"latest/contributing",title:"Contribution Guidelines",description:"This section has information on how to contribute to Headlamp. It assumes you have cloned",source:"@site/docs/latest/contributing.md",sourceDirName:"latest",slug:"/latest/contributing",permalink:"/docs/latest/contributing",draft:!1,unlisted:!1,editUrl:"https://github.com/kubernetes-sigs/headlamp/edit/main/docs/contributing.md",tags:[],version:"current",sidebarPosition:4,frontMatter:{title:"Contribution Guidelines",sidebar_label:"Contributing",sidebar_position:4},sidebar:"mainSidebar",previous:{title:"WhoAmI Plugin",permalink:"/docs/latest/tutorials/plugin-development/whoami-plugin/"},next:{title:"Development",permalink:"/docs/latest/development/"}},a={},d=[{value:"Code of Conduct",id:"code-of-conduct",level:2},{value:"Development practices",id:"development-practices",level:2},{value:"Community Monthly Call",id:"community-monthly-call",level:2},{value:"Filing an issue or feature request",id:"filing-an-issue-or-feature-request",level:2},{value:"Guidelines for Submitting an Issue",id:"guidelines-for-submitting-an-issue",level:3},{value:"Security issues",id:"security-issues",level:3},{value:"Submitting a Pull Request (PR)",id:"submitting-a-pull-request-pr",level:2},{value:"1. Run Tests and Format Your Code",id:"1-run-tests-and-format-your-code",level:3},{value:"2. Follow Commit Guidelines",id:"2-follow-commit-guidelines",level:3},{value:"Examples:",id:"examples",level:4},{value:"3. Write a Descriptive PR Description",id:"3-write-a-descriptive-pr-description",level:3},{value:"4. Use Labels for Organization",id:"4-use-labels-for-organization",level:3},{value:"Coding style",id:"coding-style",level:2},{value:"Complex contributions",id:"complex-contributions",level:2},{value:"Translations",id:"translations",level:2},{value:"Commit guidelines",id:"commit-guidelines",level:2},{value:"Testing",id:"testing",level:2}];function c(e){const n={a:"a",code:"code",em:"em",h2:"h2",h3:"h3",h4:"h4",hr:"hr",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,t.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsxs)(n.p,{children:["This section has information on how to contribute to Headlamp. It assumes you have cloned\nthis repository (or your own Github fork).\nAny contributions to the project are accepted under the terms of the project's\nlicense (",(0,s.jsx)(n.a,{href:"https://github.com/kubernetes-sigs/headlamp/blob/main/LICENSE",children:"Apache 2.0"}),")."]}),"\n",(0,s.jsx)(n.h2,{id:"code-of-conduct",children:"Code of Conduct"}),"\n",(0,s.jsxs)(n.p,{children:["Please refer to the ",(0,s.jsx)(n.a,{href:"https://kubernetes.io/community/code-of-conduct/",children:"Kubernetes Community Code of Conduct"}),"."]}),"\n",(0,s.jsx)(n.h2,{id:"development-practices",children:"Development practices"}),"\n",(0,s.jsxs)(n.p,{children:["The Headlamp project follows the ",(0,s.jsx)(n.a,{href:"https://github.com/kinvolk/contribution",children:"Kinvolk Contribution Guidelines"}),",\nwhich promotes good and consistent contribution practices across Kinvolk's\nprojects. Before starting to contribute, and in addition to this section, please\nread those guidelines."]}),"\n",(0,s.jsx)(n.h2,{id:"community-monthly-call",children:"Community Monthly Call"}),"\n",(0,s.jsx)(n.p,{children:"We hold a monthly call to discuss the project, the roadmap, and the community."}),"\n",(0,s.jsxs)(n.p,{children:["You can find Headlamp's Community Call event in its ",(0,s.jsx)(n.a,{href:"https://zoom-lfx.platform.linuxfoundation.org/meetings/headlamp?view=month",children:"CNCF calendar"}),"."]}),"\n",(0,s.jsx)(n.h2,{id:"filing-an-issue-or-feature-request",children:"Filing an issue or feature request"}),"\n",(0,s.jsxs)(n.p,{children:["Please use the ",(0,s.jsx)(n.a,{href:"https://github.com/kubernetes-sigs/headlamp/issues",children:"project's issue tracker"})," for filing any bugs you find or features\nyou think are useful."]}),"\n",(0,s.jsx)(n.h3,{id:"guidelines-for-submitting-an-issue",children:"Guidelines for Submitting an Issue"}),"\n",(0,s.jsx)(n.p,{children:"When submitting an issue, follow these guidelines to help maintainers address it efficiently:"}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"Search for Existing Issues:"})}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Use the issue tracker to see if your issue already exists. If it does, consider adding your input to the existing issue instead of opening a new one."}),"\n",(0,s.jsxs)(n.li,{children:["If the issue doesn't exist, please create a new issue using one of the templates available:\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.a,{href:"https://github.com/kubernetes-sigs/headlamp/issues/new?assignees=&labels=bug&projects=&template=bug_report.md&title=",children:"For bug related issues"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.a,{href:"https://github.com/kubernetes-sigs/headlamp/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.md&title=",children:"For feature requests"})}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"security-issues",children:"Security issues"}),"\n",(0,s.jsxs)(n.p,{children:["For filing security issues that are sensitive and should not be public, please see our ",(0,s.jsx)(n.a,{href:"https://github.com/kubernetes-sigs/headlamp/blob/main/SECURITY.md",children:"SECURITY.md"}),"."]}),"\n",(0,s.jsx)(n.h2,{id:"submitting-a-pull-request-pr",children:"Submitting a Pull Request (PR)"}),"\n",(0,s.jsx)(n.p,{children:"Follow these steps when submitting a PR to ensure it meets the project\u2019s standards."}),"\n",(0,s.jsx)(n.h3,{id:"1-run-tests-and-format-your-code",children:"1. Ru

1n Tests and Format Your Code"}),"\n",(0,s.jsx)(n.p,{children:"Run the following commands from your project directory:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"npm run frontend:test"})," - Run the test suite"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"npm run frontend:lint"})," - Format your code to match the project"]}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"These steps ensure your code is functional, well-typed, and formatted consistently."}),"\n",(0,s.jsx)(n.hr,{}),"\n",(0,s.jsx)(n.h3,{id:"2-follow-commit-guidelines",children:"2. Follow Commit Guidelines"}),"\n",(0,s.jsxs)(n.p,{children:["Use ",(0,s.jsx)(n.strong,{children:"atomic commits"})," to keep each commit focused on a single change. Follow this structure for your commit messages:"]}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.code,{children:"<area>: <description of changes>"})}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsx)(n.p,{children:"Both the title and the body of the commit message should not exceed\n72 characters in length.\ni.e. Please keep the title length under 72\ncharacters, and the wrap the body of the message at 72 characters."}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:["Commits should be atomic and self-contained. Divide logically separate changes\nto separate commits. This principle is best explained in the Linux Kernel\n",(0,s.jsx)(n.a,{href:"https://www.kernel.org/doc/html/v4.17/process/submitting-patches.html#separate-your-changes",children:"submitting patches"})," guide."]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:["Commit messages should explain the intention, ",(0,s.jsx)(n.em,{children:"why"})," something is done. This,\ntoo, is best explained in ",(0,s.jsx)(n.a,{href:"https://www.kernel.org/doc/html/v4.17/process/submitting-patches.html#describe-your-changes",children:"this section"})," from the Linux\nKernel patch submission guide."]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:["Commit titles (the first line in a commit) should be meaningful and describe\n",(0,s.jsx)(n.em,{children:"what"})," the commit does."]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsx)(n.p,{children:"Don't add code you will change in a later commit (it makes it pointless to\nreview that commit), nor create a commit to add code an earlier commit should\nhave added. Consider squashing the relevant commits instead."}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:["It's not important to retain your development history when contributing a\nchange. Use ",(0,s.jsx)(n.code,{children:"git rebase"})," to squash and order commits in a way that makes them easy to\nreview. Keep the final, well-structured commits and not your development history\nthat led to the final state."]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsx)(n.p,{children:"Consider reviewing the changes yourself before opening a PR. It is likely\nyou will catch errors when looking at your code critically and thus save the\nreviewers (and yourself) time."}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsx)(n.p,{children:"Use the PR's description as a \"cover letter\" and give the context you think\nreviewers might need. Use the PR's description to explain why you are\nproposing the change, give an overview, raise questions about yet-unresolved\nissues in your PR, list TODO items etc."}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(n.h4,{id:"examples",children:"Examples:"}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"Good"})}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"frontend: HomeButton: Fix so it navigates to home"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"backend: config: Add enable-dynamic-clusters flag"})}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"Bad"})}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"updates the manifest"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"Init feature added."})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"this adds new colors to the dashboard"})}),"\n"]}),"\n",(0,s.jsxs)(n.p,{children:["For more detailed commit practices, see Kinvolk's ",(0,s.jsx)(n.a,{href:"https://github.com/kinvolk/contribution/tree/master/topics/git.md",children:"Git contribution guidelines"}),"."]}),"\n",(0,s.jsx)(n.hr,{}),"\n",(0,s.jsx)(n.h3,{id:"3-write-a-descriptive-pr-description",children:"3. Write a Descriptive PR Description"}),"\n",(0,s.jsx)(n.p,{children:"When opening a PR, make sure to:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Summarize your changes"})," and ",(0,s.jsx)(n.strong,{children:"why"})," they are needed."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Link to the related issue"})," via ",(0,s.jsx)(n.code,{children:"fixes #ISSUE_NUMBER"}),", if applicable."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Provide steps to test"})," the changes."]}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"Example:"}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"This PR fixes the home button bug where the button did not navigate back to the homepage."})}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"Steps to Test:"})}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsx)(n.li,{children:"Click on the 'Home' button in the sidebar."}),"\n",(0,s.jsx)(n.li,{children:"Verify that it navigates to the main screen."}),"\n"]}),"\n",(0,s.jsx)(n.hr,{}),"\n",(0,s.jsx)(n.h3,{id:"4-use-labels-for-organization",children:"4. Use Labels for Organization"}),"\n",(0,s.jsx)(n.p,{children:"Add relevant labels to your PR to help with triaging and prioritization:"}),"\n",(0,s.jsx)(n.p,{children:"Example:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"enhancement"}),"\n",(0,s.jsx)(n.li,{children:"documentation"}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"coding-style",children:"Coding style"}),"\n",(0,s.jsxs)(n.p,{children:["The coding style for the ",(0,s.jsx)(n.code,{children:"backend"})," and ",(0,s.jsx)(n.code,{children:"frontend"})," should be consistent.\nFor helping and verifying that, we have go and js linters."]}),"\n",(0,s.jsxs)(n.p,{children:["For linting the ",(0,s.jsx)(n.code,{children:"backend"})," and ",(0,s.jsx)(n.code,{children:"frontend"}),", use the following commands\n(respectively):"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-bash",children:"npm run backend:lint\n"})}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-bash",children:"npm run frontend:lint\n"})}),"\n",(0,s.jsx)(n.p,{children:"The linters are also run in the CI system, so any PRs you create will be\ntested for compliance with the coding style."}),"\n",(0,s.jsx)(n.p,{children:"To speed up a review from the project's maintainers, please make sure that\nthe CI checks are passing for your PR."}),"\n",(0,s.jsx)(n.h2,{id:"complex-contributions",children:"Complex contributions"}),"\n",(0,s.jsxs)(n.p,{children:["If you have a complex contribution in mind (meaning changes in the architecture\nor a lot of LOC changed), it is advisable to first file a GitHub issue and\ndiscuss the implementation with the project's maintainers via ",(0,s.jsx)(n.a,{href:"https://kubernetes.slack.com/messages/headlamp",children:"#headlamp"})," Slack channel."]}),"\n",(0,s.jsx)(n.h2,{id:"translations",children:"Translations"}),"\n",(0,s.jsxs)(n.p,{children:["If you want to contribute to the internationalization of Headlamp, please refer to the\ndedicated ",(0,s.jsx)(n.a,{href:"./development/i18n",children:"i18n docs"}),"."]}),"\n",(0,s.jsx)(n.h2,{id:"commit-guidelines",children:"Commit guidelines"}),"\n",(0,s.jsxs)(n.p,{children:["For general guidelines on making PRs/commits easier to review, please check\nout Kinvolk's\n",(0,s.jsx)(n.a,{href:"https://github.com/kinvolk/contribution/tree/master/topics/git.md",children:"contribution guidelines on git"}),"."]}),"\n",(0,s.jsx)(n.h2,{id:"testing",children:"Testing"}),"\n",(0,s.jsx)(n.p,{children:"The frontend is tested via Storybook-related snapshots. So new components should have\nan associated story when possible."}),"\n",(0,s.jsx)(n.p,{children:"For running the frontend tests, use the following command:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-bash",children:"npm run frontend:test\n"})}),"\n",(0,s.jsx)(n.p,{children:"The backend uses go's testing and can be run by using the following command:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-bash",children:"npm run backend:test\n"})}),"\n",(0,s.jsx)(n.p,{children:"Tests will run as part of the CI after a Pull Request is open."})]})}function h(e={}){const{wrapper:n}={...(0,t.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(c,{...e})}):c(e)}}}]);