summaryrefslogtreecommitdiffstats
path: root/.github/CONTRIBUTING.md
blob: 9e27df94b90d038baff64bb8ce24bb6e33c83cf4 (plain) 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328

Contributing to ZFS on Linux

First of all, thank you for taking the time to contribute!

By using the following guidelines, you can help us make ZFS on Linux even better.

Table Of Contents

What should I know before I get started?

How Can I Contribute?

Style Guides

Helpful resources

What should I know before I get started?

Get ZFS

You can build zfs packages by following these instructions, or install stable packages from your distribution's repository.

Debug ZFS

A variety of methods and tools are available to aid ZFS developers. It's strongly recommended that when developing a patch the --enable-debug configure option should be set. This will enable additional correctness checks and all the ASSERTs to help quickly catch potential issues.

In addition, there are numerous utilities and debugging files which provide visibility into the inner workings of ZFS. The most useful of these tools are discussed in detail on the Troubleshooting page.

Where can I ask for help?

The zfs-discuss mailing list or IRC are the best places to ask for help. Please do not file support requests on the GitHub issue tracker.

How Can I Contribute?

Reporting Bugs

Please contact us via the zfs-discuss mailing list or IRC if you aren't certain that you are experiencing a bug.

If you run into an issue, please search our issue tracker first to ensure the issue hasn't been reported before. Open a new issue only if you haven't found anything similar to your issue.

You can open a new issue and search existing issues using the public issue tracker.

When opening a new issue, please include the following information at the top of the issue:

  • What distribution (with version) you are using.
  • The spl and zfs versions you are using, installation method (repository or manual compilation).
  • Describe the issue you are experiencing.
  • Describe how to reproduce the issue.
  • Including any warning/errors/backtraces from the system logs.

When a new issue is opened, it is not uncommon for developers to request additional information.

In general, the more detail you share about a problem the quicker a developer can resolve it. For example, providing a simple test case is always exceptionally helpful.

Be prepared to work with the developers investigating your issue. Your assistance is crucial in providing a quick solution. They may ask for information like:

  • Your pool configuration as reported by zdb or zpool status.
  • Your hardware configuration, such as
    • Number of CPUs.
    • Amount of memory.
    • Whether your system has ECC memory.
    • Whether it is running under a VMM/Hypervisor.
    • Kernel version.
    • Values of the spl/zfs module parameters.
  • Stack traces which may be logged to dmesg.

Suggesting Enhancements

ZFS on Linux is a widely deployed production filesystem which is under active development. The team's primary focus is on fixing known issues, improving performance, and adding compelling new features.

You can view the list of proposed features by filtering the issue tracker by the "Type: Feature" label. If you have an idea for a feature first check this list. If your idea already appears then add a +1 to the top most comment, this helps us gauge interest in that feature.

Otherwise, open a new issue and describe your proposed feature. Why is this feature needed? What problem does it solve?

Pull Requests

General

  • All pull requests must be based on the current master branch and apply without conflicts.
  • Please attempt to limit pull requests to a single commit which resolves one specific issue.
  • Make sure your commit messages are in the correct format. See the Commit Message Formats section for more information.
  • When updating a pull request squash multiple commits by performing a rebase (squash).
  • For large pull requests consider structuring your changes as a stack of logically independent patches which build on each other. This makes large changes easier to review and approve which speeds up the merging process.
  • Try to keep pull requests simple. Simple code with comments is much easier to review and approve.
  • All proposed changes must be approved by a ZFS on Linux organization member.
  • If you have an idea you'd like to discuss or which requires additional testing, consider opening it as a draft pull request. Once everything is in good shape and the details have been worked out you can remove its draft status. Any required reviews can then be finalized and the pull request merged.

Tests and Benchmarks

  • Every pull request will by tested by the buildbot on multiple platforms by running the zfs-tests.sh and zloop.sh test suites.
  • To verify your changes conform to the style guidelines, please run make checkstyle and resolve any warnings.
  • Static code analysis of each pull request is performed by the buildbot; run make lint to check your changes.
  • Test cases should be provided when appropriate. This includes making sure new features have adequate code coverage.
  • If your pull request improves performance, please include some benchmarks.
  • The pull request must pass all required ZFS Buildbot builders before being accepted. If you are experiencing intermittent TEST builder failures, you may be experiencing a test suite issue. There are also various buildbot options to control how changes are tested.

Testing

All help is appreciated! If you're in a position to run the latest code consider helping us by reporting any functional problems, performance regressions or other suspected issues. By running the latest code to a wide range of realistic workloads, configurations and architectures we're better able quickly identify and resolve potential issues.

Users can also run the ZFS Test Suite on their systems to verify ZFS is behaving as intended.

Style Guides

Coding Conventions

We currently use C Style and Coding Standards for SunOS as our coding convention.

This repository has an .editorconfig file. If your editor supports editorconfig, it will automatically respect most of this project's whitespace preferences.

Additionally, Git can help warn on whitespace problems as well:

git config --local core.whitespace trailing-space,space-before-tab,indent-with-non-tab,-tab-in-indent

Commit Message Formats

New Changes

Commit messages for new changes must meet the following guidelines:

  • In 72 characters or less, provide a summary of the change as the first line in the commit message.
  • A body which provides a description of the change. If necessary, please summarize important information such as why the proposed approach was chosen or a brief description of the bug you are resolving. Each line of the body must be 72 characters or less.
  • The last line must be a Signed-off-by: tag. See the Signed Off By section for more information.

An example commit message for new changes is provided below.

This line is a brief summary of your change

Please provide at least a couple sentences describing the
change. If necessary, please summarize decisions such as
why the proposed approach was chosen or what bug you are
attempting to solve.

Signed-off-by: Contributor <[email protected]>

OpenZFS Patch Ports

If you are porting OpenZFS patches, the commit message must meet the following guidelines:

  • The first line must be the summary line from the most important OpenZFS commit being ported. It must begin with OpenZFS dddd, dddd - where dddd are OpenZFS issue numbers.
  • Provides a Authored by: line to attribute each patch for each original author.
  • Provides the Reviewed by: and Approved by: lines from each original OpenZFS commit.
  • Provides a Ported-by: line with the developer's name followed by their email for each OpenZFS commit.
  • Provides a OpenZFS-issue: line with link for each original illumos issue.
  • Provides a OpenZFS-commit: line with link for each original OpenZFS commit.
  • If necessary, provide some porting notes to describe any deviations from the original OpenZFS commits.

An example OpenZFS patch port commit message for a single patch is provided below.

OpenZFS 1234 - Summary from the original OpenZFS commit

Authored by: Original Author <[email protected]>
Reviewed by: Reviewer One <[email protected]>
Reviewed by: Reviewer Two <[email protected]>
Approved by: Approver One <[email protected]>
Ported-by: ZFS Contributor <[email protected]>

Provide some porting notes here if necessary.

OpenZFS-issue: https://www.illumos.org/issues/1234
OpenZFS-commit: https://github.com/openzfs/openzfs/commit/abcd1234

If necessary, multiple OpenZFS patches can be combined in a single port. This is useful when you are porting a new patch and its subsequent bug fixes. An example commit message is provided below.

OpenZFS 1234, 5678 - Summary of most important OpenZFS commit

1234 Summary from original OpenZFS commit for 1234

Authored by: Original Author <[email protected]>
Reviewed by: Reviewer Two <[email protected]>
Approved by: Approver One <[email protected]>
Ported-by: ZFS Contributor <[email protected]>

Provide some porting notes here for 1234 if necessary.

OpenZFS-issue: https://www.illumos.org/issues/1234
OpenZFS-commit: https://github.com/openzfs/openzfs/commit/abcd1234

5678 Summary from original OpenZFS commit for 5678

Authored by: Original Author2 <[email protected]>
Reviewed by: Reviewer One <[email protected]>
Approved by: Approver Two <[email protected]>
Ported-by: ZFS Contributor <[email protected]>

Provide some porting notes here for 5678 if necessary.

OpenZFS-issue: https://www.illumos.org/issues/5678
OpenZFS-commit: https://github.com/openzfs/openzfs/commit/efgh5678

Coverity Defect Fixes

If you are submitting a fix to a Coverity defect, the commit message should meet the following guidelines:

  • Provides a subject line in the format of Fix coverity defects: CID dddd, dddd... where dddd represents each CID fixed by the commit.
  • Provides a body which lists each Coverity defect and how it was corrected.
  • The last line must be a Signed-off-by: tag. See the Signed Off By section for more information.

An example Coverity defect fix commit message is provided below.

Fix coverity defects: CID 12345, 67890

CID 12345: Logically dead code (DEADCODE)

Removed the if(var != 0) block because the condition could never be
satisfied.

CID 67890: Resource Leak (RESOURCE_LEAK)

Ensure free is called after allocating memory in function().

Signed-off-by: Contributor <[email protected]>

Signed Off By

A line tagged as Signed-off-by: must contain the developer's name followed by their email. This is the developer's certification that they have the right to submit the patch for inclusion into the code base and indicates agreement to the Developer's Certificate of Origin. Code without a proper signoff cannot be merged.

Git can append the Signed-off-by line to your commit messages. Simply provide the -s or --signoff option when performing a git commit. For more information about writing commit messages, visit How to Write a Git Commit Message.

Co-authored By

If someone else had part in your pull request, please add the following to the commit: Co-authored-by: Name <[email protected]> This is useful if their authorship was lost during squashing, rebasing, etc., but may be used in any situation where there are co-authors.

The email address used here should be the same as on the GitHub profile of said user. If said user does not have their email address public, please use the following instead: Co-authored-by: Name <[username]@users.noreply.github.com>

generated by cgit v1.2.3 (git 2.39.1) at 2024-12-12 21:17:19 +0000