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