github.com/openebs/node-disk-manager@v1.9.1-0.20230225014141-4531f06ffa1e/CONTRIBUTING.md (about) 1 # Contributing to Node Disk Manager(NDM) 2 3 NDM uses the standard GitHub pull requests process to review and accept contributions. There are several areas that could use your help. For starters, you could help in improving the sections in this document by either creating a new issue describing the improvement or submitting a pull request to this repository. The issues are maintained at [openebs/openebs](https://github.com/openebs/openebs/issues?q=is%3Aissue+is%3Aopen+label%3Andm) repository. 4 5 * If you are a first-time contributor, please see [Steps to Contribute](#steps-to-contribute). 6 * If you want to file an issue for a bug or feature request, please see [Filing a issue](#filing-an-issue) 7 * If you have documentation improvement ideas, go ahead and create a pull request. See [Pull Request checklist](#pull-request-checklist) 8 * If you would like to make code contributions, please start with [Setting up the Development Environment](#setting-up-your-development-environment). 9 * If you would like to work on something more involved, please connect with the OpenEBS Contributors. See [OpenEBS Community](https://github.com/openebs/openebs/tree/main/community) 10 11 ## Steps to Contribute 12 13 NDM is an Apache 2.0 Licensed project and all your commits should be signed with Developer Certificate of Origin. See [Sign your work](#sign-your-work). 14 15 * Find an issue to work on or create a new issue. The issues are maintained at [openebs/openebs](https://github.com/openebs/openebs/issues?q=is%3Aissue+is%3Aopen+label%3Andm). You can pick up from a list of [good-first-issues](https://github.com/openebs/node-disk-manager/labels/good%20first%20issue). 16 * Claim your issue by commenting your intent to work on it to avoid duplication of efforts. 17 * Fork the repository on GitHub. 18 * Create a branch from where you want to base your work (usually develop). 19 * Make your changes. If you are working on code contributions, please see [Setting up the Development Environment](#setting-up-your-development-environment). 20 * Relevant coding style guidelines are the [Go Code Review Comments](https://code.google.com/p/go-wiki/wiki/CodeReviewComments) and the _Formatting and style_ section of Peter Bourgon's [Go: Best Practices for Production Environments](http://peter.bourgon.org/go-in-production/#formatting-and-style). 21 * Commit your changes by making sure the commit messages convey the need and notes about the commit. The commit message format followed for OpenEBS projects can be found [here](https://github.com/openebs/openebs/blob/main/contribute/git-commit-message.md). 22 * Push your changes to the branch in your fork of the repository. 23 * Submit a pull request to the original repository. See [Pull Request checklist](#pull-request-checklist) 24 25 ## Filing an issue 26 ### Before filing an issue 27 28 If you are unsure whether you have found a bug, please consider asking in the [Slack](https://kubernetes.slack.com/messages/openebs) first. If 29 the behavior you are seeing is confirmed as a bug or issue, it can easily be re-raised in the [issue tracker](https://github.com/openebs/openebs/issues). 30 31 ### Filing issues 32 33 When filing an issue, make sure to answer these seven questions: 34 35 1. What version of OpenEBS are you using? 36 2. Type of disks used and the environment 37 3. What did you expect to see? 38 4. What did you see instead? 39 40 #### For maintainers 41 * We are using labelling for issue to track it more effectively. Following are valid labels for the issue. 42 - **Bug** - if issue is a **bug to existing feature** 43 - **Enhancement** - if issue is a **feature request** 44 - **Maintenance** - if issue is not related to production code. **build, document or test related issues falls into this category** 45 - **Question** - if issue is about **querying information about how product or build works, or internals of product**. 46 - **Documentation** - if issue is about **tracking the documentation work for the feature**. This label should not be applied to the issue about bug in documentations. 47 - **Good First Issue** - if issues is easy to get started with. Please make sure that issue should be ideal for beginners to dive into the code base. 48 - **Duplicate** - if issue is **duplicate of another issue** 49 - **Help Wanted** - if issue **requires extra attention** from more users/contributors 50 51 * We are using following labels for issue work-flow: 52 - **Backlog** - if issues has **not been planned for current release cycle** 53 - **Release-Note/Closed** - if issue is still open / being worked in a release 54 - **Release-Note/Open** - if issue has been **resolved in a release** 55 - **Wont Fix** - if the issue will not be worked on 56 57 **If you want to introduce a new label then you need to raise a PR to update this document with the new label details.** 58 59 ## Pull Request Checklist 60 * Rebase to the current develop branch before submitting your pull request. 61 * Commits should be as small as possible. Each commit should follow the checklist below: 62 - For code changes, add tests relevant to the fixed bug or new feature. 63 - Pass the compilation and tests - includes spell checks, formatting, etc. 64 - Commit header (first line) should convey what changed 65 - Commit body should include details such as why the changes are required and how the proposed changes help 66 - DCO Signed, please refer [signing commit](code-standard.md/sign-your-commits) 67 * If your PR is about fixing a issue or new feature, make sure you add a change-log. Refer [Adding a Change log](code-standard.md/adding-a-changelog) 68 * PR title must follow convention: `<type>(<scope>): <subject>`. 69 70 For example: 71 ``` 72 feat(partition) : add support for partitions 73 ^--^ ^-----^ ^-----------------------^ 74 | | | 75 | | +-> PR subject, summary of the changes 76 | | 77 | +-> scope of the PR, i.e. component of the project this PR is intend to update 78 | 79 +-> type of the PR. 80 ``` 81 82 Most common types are: 83 * `feat` - for new features, not a new feature for build script 84 * `fix` - for bug fixes or improvements, not a fix for build script 85 * `chore` - changes not related to production code 86 * `docs` - changes related to documentation 87 * `style` - formatting, missing semi colons, linting fix etc; no significant production code changes 88 * `test` - adding missing tests, refactoring tests; no production code change 89 * `refactor` - refactoring production code, eg. renaming a variable or function name, there should not be any significant production code changes 90 * `cherry-pick` - if PR is merged in develop branch and raised to release branch(like v0.4.x) 91 92 * If your PR is not getting reviewed, or you need a specific person to review it, please reach out to the OpenEBS Contributors. See [OpenEBS Community](https://github.com/openebs/openebs/tree/main/community) 93 --- 94 95 ### Sign your work 96 97 We use the Developer Certificate of Origin (DCO) as an additional safeguard for the OpenEBS project. This is a well established and widely used mechanism to assure contributors have confirmed their right to license their contribution under the project's license. Please read [developer-certificate-of-origin](./contribute/developer-certificate-of-origin). 98 99 Please certify it by just adding a line to every git commit message. Any PR with Commits which does not have DCO Signoff will not be accepted: 100 101 ``` 102 Signed-off-by: Random J Developer <random@developer.example.org> 103 ``` 104 105 or use the command `git commit -s -m "commit message comes here"` to sign-off on your commits. 106 107 Use your real name (sorry, no pseudonyms or anonymous contributions). If you set your `user.name` and `user.email` git configs, you can sign your commit automatically with `git commit -s`. You can also use git [aliases](https://git-scm.com/book/en/v2/Git-Basics-Git-Aliases) like `git config --global alias.ci 'commit -s'`. Now you can commit with `git ci` and the commit will be signed. 108 109 --- 110 111 ## Code Reviews 112 All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult [GitHub Help](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) for more information on using pull requests. 113 114 * If your PR is not getting reviewed or you need a specific person to review it, please reach out to the OpenEBS Contributors. See [OpenEBS Community](https://github.com/openebs/openebs/tree/main/community) 115 116 * If PR is fixing any issues from [github-issues](https://github.com/openebs/openebs/issues) then you need to mention the issue number with link in PR description. like : _fixes https://github.com/openebs/openebs/issues/2961_ 117 118 * If PR is for bug-fix and release branch(like v0.4.x) is created then cherry-pick for the same PR needs to be created against the release branch. Maintainer of the Project needs to make sure that all the bug fix after RC release are cherry-picked to release branch. 119 120 ### For maintainers 121 * We are using labelling for PR to track it more effectively. Following are valid labels for the PR. 122 - **Bug** - if PR is a **bug to existing feature** 123 - **Enhancement** - if PR is a **feature request** 124 - **Maintenance** - if PR is not related to production code. **build, document or test related PR falls into this category** 125 - **Documentation** - if PR is about **tracking the documentation work for the feature**. This label should not be applied to the PR fixing bug in documentations. 126 127 * We are using following label for PR work-flow: 128 - **pr/hold-review** - if PR is currently being developed, and is not yet ready for review 129 - **pr/hold-merge** - if PR is waiting on some dependencies, and should not be merged even if approved 130 - **pr/documentation-pending** - if the changes in PR are yet to be documented 131 - **pr/documentation-complete** - if the changes / features in the PR are already included in the documentation 132 - **pr/release-note-alpha** - the changes in this PR should be included in the alpha feature list in release note 133 - **pr/release-note** - the changes in this PR should be included in the release note 134 - **pr/upgrade-automated** - upgrade is automated for changes in this PR 135 - **pr/upgrade-pending** - the automatic upgrade for the changes in this PR are yet to be done. 136 137 * Maintainer needs to make sure that appropriate milestone and project tracker is assigned to the PR. 138 139 **If you want to introduce a new label then you need to raise a PR to update this document with the new label details.** 140 141 ## Setting up your Development Environment 142 143 This project is implemented using Go and uses the standard golang tools for development and build. In addition, this project heavily relies on Docker and Kubernetes. It is expected that the contributors: 144 - are familiar with working with Go 145 - are familiar with Docker containers 146 - are familiar with Kubernetes and have access to a Kubernetes cluster or Minikube to test the changes. 147 148 For setting up a Development environment on your local host, see the detailed instructions [here](./BUILD.md). 149 150 ## Design documents 151 The following are the design documents and flow diagrams of major components in NDM: 152 - [NDM design doc](./docs/design.md). 153 - [Disk cleanup design doc](./docs/cleanup-design.md). 154 - [NDM Exporter design doc](./docs/exporter.md). 155 - [API service design doc](./docs/api-service-dev.md).