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