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