.github/CONTRIBUTING.md

   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
   9 By 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
  13 started?](#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
  35 Helpful 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
  44 You can build zfs packages by following [these
  45 instructions](https://openzfs.github.io/openzfs-docs/Developer%20Resources/Building%20ZFS.html),
  46 or install stable packages from [your distribution's
  47 repository](https://openzfs.github.io/openzfs-docs/Getting%20Started/index.html).
  48
  49 ### Debug ZFS
  50 A variety of methods and tools are available to aid ZFS developers.
  51 It's strongly recommended that when developing a patch the `--enable-debug`
  52 configure option should be set. This will enable additional correctness
  53 checks and all the ASSERTs to help quickly catch potential issues.
  54
  55 In addition, there are numerous utilities and debugging files which
  56 provide visibility into the inner workings of ZFS.  The most useful
  57 of these tools are discussed in detail on the [Troubleshooting
  58 page](https://openzfs.github.io/openzfs-docs/Basic%20Concepts/Troubleshooting.html).
  59
  60 ### Where can I ask for help?
  61 The [zfs-discuss mailing
  62 list](https://openzfs.github.io/openzfs-docs/Project%20and%20Community/Mailing%20Lists.html)
  63 or IRC are the best places to ask for help. Please do not file
  64 support 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
  70 list](https://openzfs.github.io/openzfs-docs/Project%20and%20Community/Mailing%20Lists.html)
  71 or IRC if you aren't certain that you are experiencing a bug.
  72
  73 If you run into an issue, please search our [issue
  74 tracker](https://github.com/openzfs/zfs/issues) *first* to ensure the
  75 issue hasn't been reported before. Open a new issue only if you haven't
  76 found anything similar to your issue.
  77
  78 You can open a new issue and search existing issues using the public [issue
  79 tracker](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
  84 or 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
  89 When a new issue is opened, it is not uncommon for developers to request
  90 additional information.
  91
  92 In general, the more detail you share about a problem the quicker a
  93 developer can resolve it. For example, providing a simple test case is always
  94 exceptionally helpful.
  95
  96 Be prepared to work with the developers investigating your issue. Your
  97 assistance is crucial in providing a quick solution. They may ask for
  98 information 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
 111 OpenZFS is a widely deployed production filesystem which is under active
 112 development. The team's primary focus is on fixing known issues, improving
 113 performance, and adding compelling new features.
 114
 115 You can view the list of proposed features
 116 by filtering the issue tracker by the ["Type: Feature"
 117 label](https://github.com/openzfs/zfs/issues?q=is%3Aopen+is%3Aissue+label%3A%22Type%3A+Feature%22).
 118 If you have an idea for a feature first check this list. If your idea already
 119 appears then add a +1 to the top most comment, this helps us gauge interest
 120 in that feature.
 121
 122 Otherwise, open a new issue and describe your proposed feature.  Why is this
 123 feature needed?  What problem does it solve?
 124
 125 ### Pull Requests
 126
 127 #### General
 128
 129 * All pull requests, except backports and releases, must be based on the current master branch
 130 and should apply without conflicts.
 131 * Please attempt to limit pull requests to a single commit which resolves
 132 one 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
 138 logically independent patches which build on each other.  This makes large
 139 changes 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
 141 to 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.
 144 Once everything is in good shape and the details have been worked out you can remove its draft status.
 145 Any 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](
 149 https://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](
 151 https://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.
 155 This 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
 158 Buildbot](http://build.zfsonlinux.org/) builders before
 159 being accepted. If you are experiencing intermittent TEST
 160 builder failures, you may be experiencing a [test suite
 161 issue](https://github.com/openzfs/zfs/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Test+Suite%22).
 162 There are also various [buildbot options](https://openzfs.github.io/openzfs-docs/Developer%20Resources/Buildbot%20Options.html)
 163 to control how changes are tested.
 164
 165 ### Testing
 166 All help is appreciated! If you're in a position to run the latest code
 167 consider helping us by reporting any functional problems, performance
 168 regressions or other suspected issues. By running the latest code to a wide
 169 range of realistic workloads, configurations and architectures we're better
 170 able quickly identify and resolve potential issues.
 171
 172 Users can also run the [ZFS Test
 173 Suite](https://github.com/openzfs/zfs/tree/master/tests) on their systems
 174 to verify ZFS is behaving as intended.
 175
 176 ## Style Guides
 177
 178 ### Repository Structure
 179
 180 OpenZFS 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
 194 We currently use [C  Style  and  Coding  Standards  for
 195 SunOS](http://www.cis.upenn.edu/%7Elee/06cse480/data/cstyle.ms.pdf) as our
 196 coding convention.
 197
 198 This repository has an `.editorconfig` file. If your editor [supports
 199 editorconfig](https://editorconfig.org/#download), it will
 200 automatically respect most of this project's whitespace preferences.
 201
 202 Additionally, Git can help warn on whitespace problems as well:
 203
 204 ```
 205 git 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
 210 Commit messages for new changes must meet the following guidelines:
 211 * In 72 characters or less, provide a summary of the change as the
 212 first line in the commit message.
 213 * A body which provides a description of the change. If necessary,
 214 please summarize important information such as why the proposed
 215 approach was chosen or a brief description of the bug you are resolving.
 216 Each 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
 220 An example commit message for new changes is provided below.
 221
 222 ```
 223 This line is a brief summary of your change
 224
 225 Please provide at least a couple sentences describing the
 226 change. If necessary, please summarize decisions such as
 227 why the proposed approach was chosen or what bug you are
 228 attempting to solve.
 229
 230 Signed-off-by: Contributor <contributor@email.com>
 231 ```
 232
 233 #### Coverity Defect Fixes
 234 If you are submitting a fix to a
 235 [Coverity defect](https://scan.coverity.com/projects/zfsonlinux-zfs),
 236 the commit message should meet the following guidelines:
 237 * Provides a subject line in the format of
 238 `Fix coverity defects: CID dddd, dddd...` where `dddd` represents
 239 each CID fixed by the commit.
 240 * Provides a body which lists each Coverity defect and how it was corrected.
 241 * The last line must be a `Signed-off-by:` tag. See the
 242 [Signed Off By](#signed-off-by) section for more information.
 243
 244 An example Coverity defect fix commit message is provided below.
 245 ```
 246 Fix coverity defects: CID 12345, 67890
 247
 248 CID 12345: Logically dead code (DEADCODE)
 249
 250 Removed the if(var != 0) block because the condition could never be
 251 satisfied.
 252
 253 CID 67890: Resource Leak (RESOURCE_LEAK)
 254
 255 Ensure free is called after allocating memory in function().
 256
 257 Signed-off-by: Contributor <contributor@email.com>
 258 ```
 259
 260 #### Signed Off By
 261 A line tagged as `Signed-off-by:` must contain the developer's
 262 name followed by their email. This is the developer's certification
 263 that they have the right to submit the patch for inclusion into
 264 the code base and indicates agreement to the [Developer's Certificate
 265 of Origin](https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin).
 266 Code without a proper signoff cannot be merged.
 267
 268 Git can append the `Signed-off-by` line to your commit messages. Simply
 269 provide the `-s` or `--signoff` option when performing a `git commit`.
 270 For more information about writing commit messages, visit [How to Write
 271 a Git Commit Message](https://chris.beams.io/posts/git-commit/).
 272
 273 #### Co-authored By
 274 If someone else had part in your pull request, please add the following to the commit:
 275 `Co-authored-by: Name <gitregistered@email.address>`
 276 This is useful if their authorship was lost during squashing, rebasing, etc.,
 277 but may be used in any situation where there are co-authors.
 278
 279 The email address used here should be the same as on the GitHub profile of said user.
 280 If said user does not have their email address public, please use the following instead:
 281 `Co-authored-by: Name <[username]@users.noreply.github.com>`