Skip to content

Commit d57f03e

Browse files
gmelikovbehlendorf
gmelikov
authored and
behlendorf
committed
Add CONTRIBUTING information and templates
Guidelines for developers and users describing how they can participle in the project. Reviewed-by: Manuel Mendez <[email protected]> Reviewed-by: Giuseppe Di Natale <[email protected]> Reviewed-by: Brian Behlendorf <[email protected]> Signed-off-by: George Melikov <[email protected]> Closes openzfs#672 Closes openzfs#4776 Closes openzfs#5361
1 parent 00155d3 commit d57f03e

File tree

4 files changed

+234
-4
lines changed

4 files changed

+234
-4
lines changed

‎.github/CONTRIBUTING.md

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
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.

‎.github/ISSUE_TEMPLATE.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
<!--
2+
Thank you for reporting an issue.
3+
4+
This issue tracker is for bugs and issues only.
5+
If you need general support please use
6+
our mailing list. https://github.com/zfsonlinux/zfs/wiki/Mailing-Lists
7+
8+
Please fill in as much of the template as possible.
9+
-->
10+
11+
### System information
12+
<!-- add version after "|" character -->
13+
Type | Version/Name
14+
--- | ---
15+
Distribution Name |
16+
Distribution Version |
17+
Linux Kernel |
18+
Architecture |
19+
ZFS Version |
20+
SPL Version |
21+
<!--
22+
Commands to find ZFS/SPL versions:
23+
modinfo zfs | grep -iw version
24+
modinfo spl | grep -iw version
25+
-->
26+
27+
### Describe the problem you're observing
28+
29+
### Describe how to reproduce the problem
30+
31+
### Include any warning/errors/backtraces from the system logs
32+
<!--
33+
Example:
34+
```
35+
this is an example how log text should be marked (wrap it with ```)
36+
```
37+
-->

‎.github/PULL_REQUEST_TEMPLATE.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
<!--- Provide a general summary of your changes in the Title above -->
2+
3+
### Description
4+
<!--- Describe your changes in detail -->
5+
6+
### Motivation and Context
7+
<!--- Why is this change required? What problem does it solve? -->
8+
<!--- If it fixes an open issue, please link to the issue here. -->
9+
10+
### How Has This Been Tested?
11+
<!--- Please describe in detail how you tested your changes. -->
12+
<!--- Include details of your testing environment, and the tests you ran to -->
13+
<!--- see how your change affects other areas of the code, etc. -->
14+
<!--- If your change is a performance enhancement, please provide benchmarks here. -->
15+
16+
### Types of changes
17+
<!--- What types of changes does your code introduce? Put an `x` in all the boxes that apply: -->
18+
- [ ] Bug fix (non-breaking change which fixes an issue)
19+
- [ ] New feature (non-breaking change which adds functionality)
20+
- [ ] Performance enhancement (non-breaking change which improves efficiency)
21+
- [ ] Code cleanup (non-breaking change which makes code smaller or more readable)
22+
- [ ] Breaking change (fix or feature that would cause existing functionality to change)
23+
24+
### Checklist:
25+
<!--- Go over all the following points, and put an `x` in all the boxes that apply. -->
26+
<!--- If you're unsure about any of these, don't hesitate to ask. We're here to help! -->
27+
- [ ] My code follows the ZFS on Linux code style requirements.
28+
- [ ] I have updated the documentation accordingly.
29+
- [ ] I have read the **CONTRIBUTING** document.
30+
- [ ] I have added tests to cover my changes.
31+
- [ ] All new and existing tests passed.
32+
- [ ] Change has been approved by a ZFS on Linux member.

‎README.markdown

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,19 @@
1-
Native ZFS for Linux!
2-
1+
<p align="center"><img src="http://zfsonlinux.org/images/zfs-linux.png"/></p>
32
ZFS is an advanced file system and volume manager which was originally
43
developed for Solaris and is now maintained by the Illumos community.
54

65
ZFS on Linux, which is also known as ZoL, is currently feature complete. It
7-
includes fully functional and stable SPA, DMU, ZVOL, and ZPL layers.
6+
includes fully functional and stable SPA, DMU, ZVOL, and ZPL layers. And it's native!
7+
8+
# Official Resources
9+
* [Site](http://zfsonlinux.org)
10+
* [Wiki](https://github.com/zfsonlinux/zfs/wiki)
11+
* [Mailing lists](https://github.com/zfsonlinux/zfs/wiki/Mailing-Lists)
12+
* [OpenZFS site](http://open-zfs.org/)
813

14+
# Installation
915
Full documentation for installing ZoL on your favorite Linux distribution can
10-
be found at: <http://zfsonlinux.org>
16+
be found at [our site](http://zfsonlinux.org/).
17+
18+
# Contribute & Develop
19+
We have a separate document with [contribution guidelines](./.github/CONTRIBUTING.md).

0 commit comments

Comments
 (0)