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