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