1c40487d4SMatt Macy# Contributing to OpenZFS 2c40487d4SMatt Macy<p align="center"> 3c40487d4SMatt Macy <img alt="OpenZFS Logo" 4c40487d4SMatt Macy src="https://openzfs.github.io/openzfs-docs/_static/img/logo/480px-Open-ZFS-Secondary-Logo-Colour-halfsize.png"/> 5c40487d4SMatt Macy</p> 6c40487d4SMatt Macy 7c40487d4SMatt Macy*First of all, thank you for taking the time to contribute!* 8c40487d4SMatt Macy 9c40487d4SMatt MacyBy using the following guidelines, you can help us make OpenZFS even better. 10c40487d4SMatt Macy 11c40487d4SMatt Macy## Table Of Contents 12c40487d4SMatt Macy[What should I know before I get 13c40487d4SMatt Macystarted?](#what-should-i-know-before-i-get-started) 14c40487d4SMatt Macy 15c40487d4SMatt Macy * [Get ZFS](#get-zfs) 16c40487d4SMatt Macy * [Debug ZFS](#debug-zfs) 17c40487d4SMatt Macy * [Where can I ask for help?](#where-can-I-ask-for-help) 18c40487d4SMatt Macy 19c40487d4SMatt Macy[How Can I Contribute?](#how-can-i-contribute) 20c40487d4SMatt Macy 21c40487d4SMatt Macy * [Reporting Bugs](#reporting-bugs) 22c40487d4SMatt Macy * [Suggesting Enhancements](#suggesting-enhancements) 23c40487d4SMatt Macy * [Pull Requests](#pull-requests) 24c40487d4SMatt Macy * [Testing](#testing) 25c40487d4SMatt Macy 26c40487d4SMatt Macy[Style Guides](#style-guides) 27c40487d4SMatt Macy 28c40487d4SMatt Macy * [Coding Conventions](#coding-conventions) 29c40487d4SMatt Macy * [Commit Message Formats](#commit-message-formats) 30c40487d4SMatt Macy * [New Changes](#new-changes) 31c40487d4SMatt Macy * [OpenZFS Patch Ports](#openzfs-patch-ports) 32c40487d4SMatt Macy * [Coverity Defect Fixes](#coverity-defect-fixes) 33c40487d4SMatt Macy * [Signed Off By](#signed-off-by) 34c40487d4SMatt Macy 35c40487d4SMatt MacyHelpful resources 36c40487d4SMatt Macy 37c40487d4SMatt Macy * [OpenZFS Documentation](https://openzfs.github.io/openzfs-docs/) 38c40487d4SMatt Macy * [OpenZFS Developer Resources](http://open-zfs.org/wiki/Developer_resources) 39c40487d4SMatt Macy * [Git and GitHub for beginners](https://openzfs.github.io/openzfs-docs/Developer%20Resources/Git%20and%20GitHub%20for%20beginners.html) 40c40487d4SMatt Macy 41c40487d4SMatt Macy## What should I know before I get started? 42c40487d4SMatt Macy 43c40487d4SMatt Macy### Get ZFS 44c40487d4SMatt MacyYou can build zfs packages by following [these 45c40487d4SMatt Macyinstructions](https://openzfs.github.io/openzfs-docs/Developer%20Resources/Building%20ZFS.html), 46c40487d4SMatt Macyor install stable packages from [your distribution's 47c40487d4SMatt Macyrepository](https://openzfs.github.io/openzfs-docs/Getting%20Started/index.html). 48c40487d4SMatt Macy 49c40487d4SMatt Macy### Debug ZFS 50c40487d4SMatt MacyA variety of methods and tools are available to aid ZFS developers. 51c40487d4SMatt MacyIt's strongly recommended that when developing a patch the `--enable-debug` 52c40487d4SMatt Macyconfigure option should be set. This will enable additional correctness 53c40487d4SMatt Macychecks and all the ASSERTs to help quickly catch potential issues. 54c40487d4SMatt Macy 55c40487d4SMatt MacyIn addition, there are numerous utilities and debugging files which 56c40487d4SMatt Macyprovide visibility into the inner workings of ZFS. The most useful 57c40487d4SMatt Macyof these tools are discussed in detail on the [Troubleshooting 58c40487d4SMatt Macypage](https://openzfs.github.io/openzfs-docs/Basic%20Concepts/Troubleshooting.html). 59c40487d4SMatt Macy 60c40487d4SMatt Macy### Where can I ask for help? 61c40487d4SMatt MacyThe [zfs-discuss mailing 62c40487d4SMatt Macylist](https://openzfs.github.io/openzfs-docs/Project%20and%20Community/Mailing%20Lists.html) 63c40487d4SMatt Macyor IRC are the best places to ask for help. Please do not file 64c40487d4SMatt Macysupport requests on the GitHub issue tracker. 65c40487d4SMatt Macy 66c40487d4SMatt Macy## How Can I Contribute? 67c40487d4SMatt Macy 68c40487d4SMatt Macy### Reporting Bugs 69c40487d4SMatt Macy*Please* contact us via the [zfs-discuss mailing 70c40487d4SMatt Macylist](https://openzfs.github.io/openzfs-docs/Project%20and%20Community/Mailing%20Lists.html) 71c40487d4SMatt Macyor IRC if you aren't certain that you are experiencing a bug. 72c40487d4SMatt Macy 73c40487d4SMatt MacyIf you run into an issue, please search our [issue 74c40487d4SMatt Macytracker](https://github.com/openzfs/zfs/issues) *first* to ensure the 75c40487d4SMatt Macyissue hasn't been reported before. Open a new issue only if you haven't 76c40487d4SMatt Macyfound anything similar to your issue. 77c40487d4SMatt Macy 78c40487d4SMatt MacyYou can open a new issue and search existing issues using the public [issue 79c40487d4SMatt Macytracker](https://github.com/openzfs/zfs/issues). 80c40487d4SMatt Macy 81c40487d4SMatt Macy#### When opening a new issue, please include the following information at the top of the issue: 82c40487d4SMatt Macy* What distribution (with version) you are using. 83c40487d4SMatt Macy* The spl and zfs versions you are using, installation method (repository 84c40487d4SMatt Macyor manual compilation). 85c40487d4SMatt Macy* Describe the issue you are experiencing. 86c40487d4SMatt Macy* Describe how to reproduce the issue. 87c40487d4SMatt Macy* Including any warning/errors/backtraces from the system logs. 88c40487d4SMatt Macy 89c40487d4SMatt MacyWhen a new issue is opened, it is not uncommon for developers to request 90c40487d4SMatt Macyadditional information. 91c40487d4SMatt Macy 92c40487d4SMatt MacyIn general, the more detail you share about a problem the quicker a 93c40487d4SMatt Macydeveloper can resolve it. For example, providing a simple test case is always 94c40487d4SMatt Macyexceptionally helpful. 95c40487d4SMatt Macy 96c40487d4SMatt MacyBe prepared to work with the developers investigating your issue. Your 97c40487d4SMatt Macyassistance is crucial in providing a quick solution. They may ask for 98c40487d4SMatt Macyinformation like: 99c40487d4SMatt Macy 100c40487d4SMatt Macy* Your pool configuration as reported by `zdb` or `zpool status`. 101c40487d4SMatt Macy* Your hardware configuration, such as 102c40487d4SMatt Macy * Number of CPUs. 103c40487d4SMatt Macy * Amount of memory. 104c40487d4SMatt Macy * Whether your system has ECC memory. 105c40487d4SMatt Macy * Whether it is running under a VMM/Hypervisor. 106c40487d4SMatt Macy * Kernel version. 107c40487d4SMatt Macy * Values of the spl/zfs module parameters. 108c40487d4SMatt Macy* Stack traces which may be logged to `dmesg`. 109c40487d4SMatt Macy 110c40487d4SMatt Macy### Suggesting Enhancements 111c40487d4SMatt MacyOpenZFS is a widely deployed production filesystem which is under active 112c40487d4SMatt Macydevelopment. The team's primary focus is on fixing known issues, improving 113c40487d4SMatt Macyperformance, and adding compelling new features. 114c40487d4SMatt Macy 115c40487d4SMatt MacyYou can view the list of proposed features 116c40487d4SMatt Macyby filtering the issue tracker by the ["Type: Feature" 117c40487d4SMatt Macylabel](https://github.com/openzfs/zfs/issues?q=is%3Aopen+is%3Aissue+label%3A%22Type%3A+Feature%22). 118c40487d4SMatt MacyIf you have an idea for a feature first check this list. If your idea already 119c40487d4SMatt Macyappears then add a +1 to the top most comment, this helps us gauge interest 120c40487d4SMatt Macyin that feature. 121c40487d4SMatt Macy 122c40487d4SMatt MacyOtherwise, open a new issue and describe your proposed feature. Why is this 123c40487d4SMatt Macyfeature needed? What problem does it solve? 124c40487d4SMatt Macy 125c40487d4SMatt Macy### Pull Requests 126c40487d4SMatt Macy 127c40487d4SMatt Macy#### General 128c40487d4SMatt Macy 1297877fdebSMatt Macy* All pull requests, except backports and releases, must be based on the current master branch 1307877fdebSMatt Macyand should apply without conflicts. 131c40487d4SMatt Macy* Please attempt to limit pull requests to a single commit which resolves 132c40487d4SMatt Macyone specific issue. 133c40487d4SMatt Macy* Make sure your commit messages are in the correct format. See the 134c40487d4SMatt Macy[Commit Message Formats](#commit-message-formats) section for more information. 135c40487d4SMatt Macy* When updating a pull request squash multiple commits by performing a 136c40487d4SMatt Macy[rebase](https://git-scm.com/docs/git-rebase) (squash). 137c40487d4SMatt Macy* For large pull requests consider structuring your changes as a stack of 138c40487d4SMatt Macylogically independent patches which build on each other. This makes large 139c40487d4SMatt Macychanges easier to review and approve which speeds up the merging process. 140c40487d4SMatt Macy* Try to keep pull requests simple. Simple code with comments is much easier 141c40487d4SMatt Macyto review and approve. 142c40487d4SMatt Macy* All proposed changes must be approved by an OpenZFS organization member. 143c40487d4SMatt Macy* If you have an idea you'd like to discuss or which requires additional testing, consider opening it as a draft pull request. 144c40487d4SMatt MacyOnce everything is in good shape and the details have been worked out you can remove its draft status. 145c40487d4SMatt MacyAny required reviews can then be finalized and the pull request merged. 146c40487d4SMatt Macy 147c40487d4SMatt Macy#### Tests and Benchmarks 148c40487d4SMatt Macy* Every pull request will by tested by the buildbot on multiple platforms by running the [zfs-tests.sh and zloop.sh]( 149c40487d4SMatt Macyhttps://openzfs.github.io/openzfs-docs/Developer%20Resources/Building%20ZFS.html#running-zloop-sh-and-zfs-tests-sh) test suites. 150c40487d4SMatt Macy* To verify your changes conform to the [style guidelines]( 151c40487d4SMatt Macyhttps://github.com/openzfs/zfs/blob/master/.github/CONTRIBUTING.md#style-guides 152c40487d4SMatt Macy), please run `make checkstyle` and resolve any warnings. 153c40487d4SMatt Macy* Static code analysis of each pull request is performed by the buildbot; run `make lint` to check your changes. 154c40487d4SMatt Macy* Test cases should be provided when appropriate. 155c40487d4SMatt MacyThis includes making sure new features have adequate code coverage. 156c40487d4SMatt Macy* If your pull request improves performance, please include some benchmarks. 157c40487d4SMatt Macy* The pull request must pass all required [ZFS 158c40487d4SMatt MacyBuildbot](http://build.zfsonlinux.org/) builders before 159c40487d4SMatt Macybeing accepted. If you are experiencing intermittent TEST 160c40487d4SMatt Macybuilder failures, you may be experiencing a [test suite 161c40487d4SMatt Macyissue](https://github.com/openzfs/zfs/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Test+Suite%22). 162c40487d4SMatt MacyThere are also various [buildbot options](https://openzfs.github.io/openzfs-docs/Developer%20Resources/Buildbot%20Options.html) 163c40487d4SMatt Macyto control how changes are tested. 164c40487d4SMatt Macy 165c40487d4SMatt Macy### Testing 166c40487d4SMatt MacyAll help is appreciated! If you're in a position to run the latest code 167c40487d4SMatt Macyconsider helping us by reporting any functional problems, performance 168c40487d4SMatt Macyregressions or other suspected issues. By running the latest code to a wide 169c40487d4SMatt Macyrange of realistic workloads, configurations and architectures we're better 170c40487d4SMatt Macyable quickly identify and resolve potential issues. 171c40487d4SMatt Macy 172c40487d4SMatt MacyUsers can also run the [ZFS Test 173c40487d4SMatt MacySuite](https://github.com/openzfs/zfs/tree/master/tests) on their systems 174c40487d4SMatt Macyto verify ZFS is behaving as intended. 175c40487d4SMatt Macy 176c40487d4SMatt Macy## Style Guides 177c40487d4SMatt Macy 178c40487d4SMatt Macy### Repository Structure 179c40487d4SMatt Macy 180c40487d4SMatt MacyOpenZFS uses a standardised branching structure. 181c40487d4SMatt Macy- The "development and main branch", is the branch all development should be based on. 182c40487d4SMatt Macy- "Release branches" contain the latest released code for said version. 183c40487d4SMatt Macy- "Staging branches" contain selected commits prior to being released. 184c40487d4SMatt Macy 185c40487d4SMatt Macy**Branch Names:** 186c40487d4SMatt Macy- Development and Main branch: `master` 187c40487d4SMatt Macy- Release branches: `zfs-$VERSION-release` 188c40487d4SMatt Macy- Staging branches: `zfs-$VERSION-staging` 189c40487d4SMatt Macy 190c40487d4SMatt Macy`$VERSION` should be replaced with the `major.minor` version number. 191c40487d4SMatt Macy_(This is the version number without the `.patch` version at the end)_ 192c40487d4SMatt Macy 193c40487d4SMatt Macy### Coding Conventions 194c40487d4SMatt MacyWe currently use [C Style and Coding Standards for 195c40487d4SMatt MacySunOS](http://www.cis.upenn.edu/%7Elee/06cse480/data/cstyle.ms.pdf) as our 196c40487d4SMatt Macycoding convention. 197c40487d4SMatt Macy 198c40487d4SMatt MacyThis repository has an `.editorconfig` file. If your editor [supports 199c40487d4SMatt Macyeditorconfig](https://editorconfig.org/#download), it will 200c40487d4SMatt Macyautomatically respect most of this project's whitespace preferences. 201c40487d4SMatt Macy 202c40487d4SMatt MacyAdditionally, Git can help warn on whitespace problems as well: 203c40487d4SMatt Macy 204c40487d4SMatt Macy``` 205c40487d4SMatt Macygit config --local core.whitespace trailing-space,space-before-tab,indent-with-non-tab,-tab-in-indent 206c40487d4SMatt Macy``` 207c40487d4SMatt Macy 208c40487d4SMatt Macy### Commit Message Formats 209c40487d4SMatt Macy#### New Changes 210c40487d4SMatt MacyCommit messages for new changes must meet the following guidelines: 211c40487d4SMatt Macy* In 72 characters or less, provide a summary of the change as the 212c40487d4SMatt Macyfirst line in the commit message. 213c40487d4SMatt Macy* A body which provides a description of the change. If necessary, 214c40487d4SMatt Macyplease summarize important information such as why the proposed 215c40487d4SMatt Macyapproach was chosen or a brief description of the bug you are resolving. 216c40487d4SMatt MacyEach line of the body must be 72 characters or less. 217c40487d4SMatt Macy* The last line must be a `Signed-off-by:` tag. See the 218c40487d4SMatt Macy[Signed Off By](#signed-off-by) section for more information. 219c40487d4SMatt Macy 220c40487d4SMatt MacyAn example commit message for new changes is provided below. 221c40487d4SMatt Macy 222c40487d4SMatt Macy``` 223c40487d4SMatt MacyThis line is a brief summary of your change 224c40487d4SMatt Macy 225c40487d4SMatt MacyPlease provide at least a couple sentences describing the 226c40487d4SMatt Macychange. If necessary, please summarize decisions such as 227c40487d4SMatt Macywhy the proposed approach was chosen or what bug you are 228c40487d4SMatt Macyattempting to solve. 229c40487d4SMatt Macy 230c40487d4SMatt MacySigned-off-by: Contributor <contributor@email.com> 231c40487d4SMatt Macy``` 232c40487d4SMatt Macy 233c40487d4SMatt Macy#### Coverity Defect Fixes 234c40487d4SMatt MacyIf you are submitting a fix to a 235c40487d4SMatt Macy[Coverity defect](https://scan.coverity.com/projects/zfsonlinux-zfs), 236c40487d4SMatt Macythe commit message should meet the following guidelines: 237c40487d4SMatt Macy* Provides a subject line in the format of 238c40487d4SMatt Macy`Fix coverity defects: CID dddd, dddd...` where `dddd` represents 239c40487d4SMatt Macyeach CID fixed by the commit. 240c40487d4SMatt Macy* Provides a body which lists each Coverity defect and how it was corrected. 241c40487d4SMatt Macy* The last line must be a `Signed-off-by:` tag. See the 242c40487d4SMatt Macy[Signed Off By](#signed-off-by) section for more information. 243c40487d4SMatt Macy 244c40487d4SMatt MacyAn example Coverity defect fix commit message is provided below. 245c40487d4SMatt Macy``` 246c40487d4SMatt MacyFix coverity defects: CID 12345, 67890 247c40487d4SMatt Macy 248c40487d4SMatt MacyCID 12345: Logically dead code (DEADCODE) 249c40487d4SMatt Macy 250c40487d4SMatt MacyRemoved the if(var != 0) block because the condition could never be 251c40487d4SMatt Macysatisfied. 252c40487d4SMatt Macy 253c40487d4SMatt MacyCID 67890: Resource Leak (RESOURCE_LEAK) 254c40487d4SMatt Macy 255c40487d4SMatt MacyEnsure free is called after allocating memory in function(). 256c40487d4SMatt Macy 257c40487d4SMatt MacySigned-off-by: Contributor <contributor@email.com> 258c40487d4SMatt Macy``` 259c40487d4SMatt Macy 260c40487d4SMatt Macy#### Signed Off By 261c40487d4SMatt MacyA line tagged as `Signed-off-by:` must contain the developer's 262c40487d4SMatt Macyname followed by their email. This is the developer's certification 263c40487d4SMatt Macythat they have the right to submit the patch for inclusion into 264c40487d4SMatt Macythe code base and indicates agreement to the [Developer's Certificate 265c40487d4SMatt Macyof Origin](https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin). 266c40487d4SMatt MacyCode without a proper signoff cannot be merged. 267c40487d4SMatt Macy 268c40487d4SMatt MacyGit can append the `Signed-off-by` line to your commit messages. Simply 269c40487d4SMatt Macyprovide the `-s` or `--signoff` option when performing a `git commit`. 270c40487d4SMatt MacyFor more information about writing commit messages, visit [How to Write 271c40487d4SMatt Macya Git Commit Message](https://chris.beams.io/posts/git-commit/). 272c40487d4SMatt Macy 273c40487d4SMatt Macy#### Co-authored By 274c40487d4SMatt MacyIf someone else had part in your pull request, please add the following to the commit: 275c40487d4SMatt Macy`Co-authored-by: Name <gitregistered@email.address>` 276c40487d4SMatt MacyThis is useful if their authorship was lost during squashing, rebasing, etc., 277c40487d4SMatt Macybut may be used in any situation where there are co-authors. 278c40487d4SMatt Macy 279c40487d4SMatt MacyThe email address used here should be the same as on the GitHub profile of said user. 280c40487d4SMatt MacyIf said user does not have their email address public, please use the following instead: 281c40487d4SMatt Macy`Co-authored-by: Name <[username]@users.noreply.github.com>` 282