.github/CONTRIBUTING.md

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