projects / mirror_zfs.git / blame
| Commit | Line | Data |
|---|---|---|
| d57f03e4 GM |
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. |