Add CONTRIBUTING information and templates
Guidelines for developers and users describing how they can participle in the project. Reviewed-by: Manuel Mendez <mmendez534@gmail.com> Reviewed-by: Giuseppe Di Natale <dinatale2@llnl.gov> Reviewed-by: Brian Behlendorf <behlendorf1@llnl.gov> Signed-off-by: George Melikov <mail@gmelikov.ru> Closes #672 Closes #4776 Closes #5361
This commit is contained in:
George Melikov
Brian Behlendorf
parent
00155d395f
commit
d57f03e40e
|
|
@ -0,0 +1,152 @@
|
|||
# Contributing to ZFS on Linux
|
||||
<p align="center"><img src="http://zfsonlinux.org/images/zfs-linux.png"/></p>
|
||||
|
||||
*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?](#what-should-i-know-before-i-get-started)
|
||||
|
||||
* [Get ZFS](#get-zfs)
|
||||
* [Debug ZFS](#debug-zfs)
|
||||
* [Where can I ask for help?](#where-can-I-ask-for-help)
|
||||
|
||||
[How Can I Contribute?](#how-can-i-contribute)
|
||||
|
||||
* [Reporting Bugs](#reporting-bugs)
|
||||
* [Suggesting Enhancements](#suggesting-enhancements)
|
||||
* [Pull Requests](#pull-requests)
|
||||
* [Testing](#testing)
|
||||
|
||||
[Style Guides](#style-guides)
|
||||
|
||||
* [Coding Conventions](#coding-conventions)
|
||||
|
||||
Helpful resources
|
||||
|
||||
* [ZFS on Linux wiki](https://github.com/zfsonlinux/zfs/wiki)
|
||||
* [OpenZFS Documentation](http://open-zfs.org/wiki/Developer_resources)
|
||||
|
||||
## What should I know before I get started?
|
||||
|
||||
### Get ZFS
|
||||
You can build zfs packages by following [these
|
||||
instructions](https://github.com/zfsonlinux/zfs/wiki/Building-ZFS),
|
||||
or install stable packages from [your distribution's
|
||||
repository](https://github.com/zfsonlinux/zfs/wiki/Getting-Started).
|
||||
|
||||
### 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 in to the inner workings of ZFS. The most useful
|
||||
of these tools are discussed in detail on the [debugging ZFS wiki
|
||||
page](https://github.com/zfsonlinux/zfs/wiki/Debugging).
|
||||
|
||||
### Where can I ask for help?
|
||||
The [mailing list](https://github.com/zfsonlinux/zfs/wiki/Mailing-Lists)
|
||||
is the best place to ask for help.
|
||||
|
||||
## How Can I Contribute?
|
||||
|
||||
### Reporting Bugs
|
||||
*Please* contact us via the [mailing
|
||||
list](https://github.com/zfsonlinux/zfs/wiki/Mailing-Lists) if you aren't
|
||||
certain that you are experiencing a bug.
|
||||
|
||||
If you run into an issue, please search our [issue
|
||||
tracker](https://github.com/zfsonlinux/zfs/issues) *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](https://github.com/zfsonlinux/zfs/issues).
|
||||
|
||||
#### 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 ["Feature"
|
||||
label](https://github.com/zfsonlinux/zfs/issues?q=is%3Aopen+is%3Aissue+label%3AFeature).
|
||||
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
|
||||
* 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.
|
||||
* When updating a pull request squash multiple commits by performing a
|
||||
[rebase](https://git-scm.com/docs/git-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.
|
||||
* Test cases should be provided when appropriate.
|
||||
* If your pull request improves performance, please include some benchmarks.
|
||||
* The pull request must pass all required [ZFS
|
||||
Buildbot](http://build.zfsonlinux.org/) builders before
|
||||
being accepted. If you are experiencing intermittent TEST
|
||||
builder failures, you may be experiencing a [test suite
|
||||
issue](https://github.com/zfsonlinux/zfs/issues?q=is%3Aissue+is%3Aopen+label%3A%22Test+Suite%22).
|
||||
* All proposed changes must be approved by a ZFS on Linux organization member.
|
||||
|
||||
### 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](https://github.com/zfsonlinux/zfs/tree/master/tests) on their systems
|
||||
to verify ZFS is behaving as intended.
|
||||
|
||||
## Style Guides
|
||||
|
||||
### Coding Conventions
|
||||
We currently use [C Style and Coding Standards for
|
||||
SunOS](http://www.cis.upenn.edu/%7Elee/06cse480/data/cstyle.ms.pdf) as our
|
||||
coding convention.
|
||||
|
|
@ -0,0 +1,37 @@
|
|||
<!--
|
||||
Thank you for reporting an issue.
|
||||
|
||||
This issue tracker is for bugs and issues only.
|
||||
If you need general support please use
|
||||
our mailing list. https://github.com/zfsonlinux/zfs/wiki/Mailing-Lists
|
||||
|
||||
Please fill in as much of the template as possible.
|
||||
-->
|
||||
|
||||
### System information
|
||||
<!-- add version after "|" character -->
|
||||
Type | Version/Name
|
||||
--- | ---
|
||||
Distribution Name |
|
||||
Distribution Version |
|
||||
Linux Kernel |
|
||||
Architecture |
|
||||
ZFS Version |
|
||||
SPL Version |
|
||||
<!--
|
||||
Commands to find ZFS/SPL versions:
|
||||
modinfo zfs | grep -iw version
|
||||
modinfo spl | grep -iw version
|
||||
-->
|
||||
|
||||
### Describe the problem you're observing
|
||||
|
||||
### Describe how to reproduce the problem
|
||||
|
||||
### Include any warning/errors/backtraces from the system logs
|
||||
<!--
|
||||
Example:
|
||||
```
|
||||
this is an example how log text should be marked (wrap it with ```)
|
||||
```
|
||||
-->
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
<!--- Provide a general summary of your changes in the Title above -->
|
||||
|
||||
### Description
|
||||
<!--- Describe your changes in detail -->
|
||||
|
||||
### Motivation and Context
|
||||
<!--- Why is this change required? What problem does it solve? -->
|
||||
<!--- If it fixes an open issue, please link to the issue here. -->
|
||||
|
||||
### How Has This Been Tested?
|
||||
<!--- Please describe in detail how you tested your changes. -->
|
||||
<!--- Include details of your testing environment, and the tests you ran to -->
|
||||
<!--- see how your change affects other areas of the code, etc. -->
|
||||
<!--- If your change is a performance enhancement, please provide benchmarks here. -->
|
||||
|
||||
### Types of changes
|
||||
<!--- What types of changes does your code introduce? Put an `x` in all the boxes that apply: -->
|
||||
- [ ] Bug fix (non-breaking change which fixes an issue)
|
||||
- [ ] New feature (non-breaking change which adds functionality)
|
||||
- [ ] Performance enhancement (non-breaking change which improves efficiency)
|
||||
- [ ] Code cleanup (non-breaking change which makes code smaller or more readable)
|
||||
- [ ] Breaking change (fix or feature that would cause existing functionality to change)
|
||||
|
||||
### Checklist:
|
||||
<!--- Go over all the following points, and put an `x` in all the boxes that apply. -->
|
||||
<!--- If you're unsure about any of these, don't hesitate to ask. We're here to help! -->
|
||||
- [ ] My code follows the ZFS on Linux code style requirements.
|
||||
- [ ] I have updated the documentation accordingly.
|
||||
- [ ] I have read the **CONTRIBUTING** document.
|
||||
- [ ] I have added tests to cover my changes.
|
||||
- [ ] All new and existing tests passed.
|
||||
- [ ] Change has been approved by a ZFS on Linux member.
|
||||
|
|
@ -1,10 +1,19 @@
|
|||
Native ZFS for Linux!
|
||||
|
||||
<p align="center"><img src="http://zfsonlinux.org/images/zfs-linux.png"/></p>
|
||||
ZFS is an advanced file system and volume manager which was originally
|
||||
developed for Solaris and is now maintained by the Illumos community.
|
||||
|
||||
ZFS on Linux, which is also known as ZoL, is currently feature complete. It
|
||||
includes fully functional and stable SPA, DMU, ZVOL, and ZPL layers.
|
||||
includes fully functional and stable SPA, DMU, ZVOL, and ZPL layers. And it's native!
|
||||
|
||||
# Official Resources
|
||||
* [Site](http://zfsonlinux.org)
|
||||
* [Wiki](https://github.com/zfsonlinux/zfs/wiki)
|
||||
* [Mailing lists](https://github.com/zfsonlinux/zfs/wiki/Mailing-Lists)
|
||||
* [OpenZFS site](http://open-zfs.org/)
|
||||
|
||||
# Installation
|
||||
Full documentation for installing ZoL on your favorite Linux distribution can
|
||||
be found at: <http://zfsonlinux.org>
|
||||
be found at [our site](http://zfsonlinux.org/).
|
||||
|
||||
# Contribute & Develop
|
||||
We have a separate document with [contribution guidelines](./.github/CONTRIBUTING.md).
|
||||
Loading…
Reference in New Issue