.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
  31 Helpful resources
  32
  33   * [ZFS on Linux wiki](https://github.com/zfsonlinux/zfs/wiki)
  34   * [OpenZFS Documentation](http://open-zfs.org/wiki/Developer_resources)
  35
  36 ## What should I know before I get started?
  37
  38 ### Get ZFS
  39 You can build zfs packages by following [these
  40 instructions](https://github.com/zfsonlinux/zfs/wiki/Building-ZFS),
  41 or install stable packages from [your distribution's
  42 repository](https://github.com/zfsonlinux/zfs/wiki/Getting-Started).
  43
  44 ### Debug ZFS
  45 A variety of methods and tools are available to aid ZFS developers.
  46 It's strongly recommended that when developing a patch the `--enable-debug`
  47 configure option should be set. This will enable additional correctness
  48 checks and all the ASSERTs to help quickly catch potential issues.
  49
  50 In addition, there are numerous utilities and debugging files which
  51 provide visibility in to the inner workings of ZFS.  The most useful
  52 of these tools are discussed in detail on the [debugging ZFS wiki
  53 page](https://github.com/zfsonlinux/zfs/wiki/Debugging).
  54
  55 ### Where can I ask for help?
  56 The [mailing list](https://github.com/zfsonlinux/zfs/wiki/Mailing-Lists)
  57 is the best place to ask for help.
  58
  59 ## How Can I Contribute?
  60
  61 ### Reporting Bugs
  62 *Please* contact us via the [mailing
  63 list](https://github.com/zfsonlinux/zfs/wiki/Mailing-Lists) if you aren't
  64 certain that you are experiencing a bug.
  65
  66 If you run into an issue, please search our [issue
  67 tracker](https://github.com/zfsonlinux/zfs/issues) *first* to ensure the
  68 issue hasn't been reported before. Open a new issue only if you haven't
  69 found anything similar to your issue.
  70
  71 You can open a new issue and search existing issues using the public [issue
  72 tracker](https://github.com/zfsonlinux/zfs/issues).
  73
  74 #### When opening a new issue, please include the following information at the top of the issue:
  75 * What distribution (with version) you are using.
  76 * The spl and zfs versions you are using, installation method (repository
  77 or manual compilation).
  78 * Describe the issue you are experiencing.
  79 * Describe how to reproduce the issue.
  80 * Including any warning/errors/backtraces from the system logs.
  81
  82 When a new issue is opened, it is not uncommon for developers to request
  83 additional information.
  84
  85 In general, the more detail you share about a problem the quicker a
  86 developer can resolve it. For example, providing a simple test case is always
  87 exceptionally helpful.
  88
  89 Be prepared to work with the developers investigating your issue. Your
  90 assistance is crucial in providing a quick solution. They may ask for
  91 information like:
  92
  93 * Your pool configuration as reported by `zdb` or `zpool status`.
  94 * Your hardware configuration, such as
  95   * Number of CPUs.
  96   * Amount of memory.
  97   * Whether your system has ECC memory.
  98   * Whether it is running under a VMM/Hypervisor.
  99   * Kernel version.
 100   * Values of the spl/zfs module parameters.
 101 * Stack traces which may be logged to `dmesg`.
 102
 103 ### Suggesting Enhancements
 104 ZFS on Linux is a widely deployed production filesystem which is under
 105 active development. The team's primary focus is on fixing known issues,
 106 improving performance, and adding compelling new features.
 107
 108 You can view the list of proposed features
 109 by filtering the issue tracker by the ["Feature"
 110 label](https://github.com/zfsonlinux/zfs/issues?q=is%3Aopen+is%3Aissue+label%3AFeature).
 111 If you have an idea for a feature first check this list. If your idea already
 112 appears then add a +1 to the top most comment, this helps us gauge interest
 113 in that feature.
 114
 115 Otherwise, open a new issue and describe your proposed feature.  Why is this
 116 feature needed?  What problem does it solve?
 117
 118 ### Pull Requests
 119 * All pull requests must be based on the current master branch and apply
 120 without conflicts.
 121 * Please attempt to limit pull requests to a single commit which resolves
 122 one specific issue.
 123 * Make sure your commit messages are in the correct format. See the
 124 [Commit Message Formats](#commit-message-formats) section for more information.
 125 * When updating a pull request squash multiple commits by performing a
 126 [rebase](https://git-scm.com/docs/git-rebase) (squash).
 127 * For large pull requests consider structuring your changes as a stack of
 128 logically independent patches which build on each other.  This makes large
 129 changes easier to review and approve which speeds up the merging process.
 130 * Try to keep pull requests simple. Simple code with comments is much easier
 131 to review and approve.
 132 * Test cases should be provided when appropriate.
 133 * If your pull request improves performance, please include some benchmarks.
 134 * The pull request must pass all required [ZFS
 135 Buildbot](http://build.zfsonlinux.org/) builders before
 136 being accepted. If you are experiencing intermittent TEST
 137 builder failures, you may be experiencing a [test suite
 138 issue](https://github.com/zfsonlinux/zfs/issues?q=is%3Aissue+is%3Aopen+label%3A%22Test+Suite%22).
 139 * All proposed changes must be approved by a ZFS on Linux organization member.
 140
 141 ### Testing
 142 All help is appreciated! If you're in a position to run the latest code
 143 consider helping us by reporting any functional problems, performance
 144 regressions or other suspected issues. By running the latest code to a wide
 145 range of realistic workloads, configurations and architectures we're better
 146 able quickly identify and resolve potential issues.
 147
 148 Users can also run the [ZFS Test
 149 Suite](https://github.com/zfsonlinux/zfs/tree/master/tests) on their systems
 150 to verify ZFS is behaving as intended.
 151
 152 ## Style Guides
 153
 154 ### Coding Conventions
 155 We currently use [C  Style  and  Coding  Standards  for
 156 SunOS](http://www.cis.upenn.edu/%7Elee/06cse480/data/cstyle.ms.pdf) as our
 157 coding convention.
 158
 159 ### Commit Message Formats
 160 #### New Changes
 161 Commit messages for new changes must meet the following guidelines:
 162 * In 50 characters or less, provide a summary of the change as the
 163 first line in the commit message.
 164 * A body which provides a description of the change. If necessary,
 165 please summarize important information such as why the proposed
 166 approach was chosen or a brief description of the bug you are resolving.
 167 Each line of the body must be 72 characters or less.
 168 * The last line must be a `Signed-off-by:` line with the developer's
 169 name followed by their email.
 170
 171 Git can append the `Signed-off-by` line to your commit messages. Simply
 172 provide the `-s` or `--signoff` option when performing a `git commit`.
 173 For more information about writing commit messages, visit [How to Write
 174 a Git Commit Message](https://chris.beams.io/posts/git-commit/).
 175 An example commit message 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 an OpenZFS patch, the commit message must meet
 190 the following guidelines:
 191 * The first line must be the summary line from the OpenZFS commit.
 192 It must begin with `OpenZFS dddd - ` where `dddd` is the OpenZFS issue number.
 193 * Provides a `Authored by:` line to attribute the patch to the original author.
 194 * Provides the `Reviewed by:` and `Approved by:` lines from the original
 195 OpenZFS commit.
 196 * Provides a `Ported-by:` line with the developer's name followed by
 197 their email.
 198 * Provides a `OpenZFS-issue:` line which is a link to the original illumos
 199 issue.
 200 * Provides a `OpenZFS-commit:` line which links back to the original OpenZFS
 201 commit.
 202 * If necessary, provide some porting notes to describe any deviations from
 203 the original OpenZFS commit.
 204
 205 An example OpenZFS patch port commit message is provided 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 ```