From d57f03e40ec3bbf109e75b83699b58157b9a867d Mon Sep 17 00:00:00 2001 From: George Melikov Date: Fri, 9 Dec 2016 20:48:12 +0100 Subject: [PATCH] Add CONTRIBUTING information and templates Guidelines for developers and users describing how they can participle in the project. Reviewed-by: Manuel Mendez Reviewed-by: Giuseppe Di Natale Reviewed-by: Brian Behlendorf Signed-off-by: George Melikov Closes #672 Closes #4776 Closes #5361 --- .github/CONTRIBUTING.md | 152 +++++++++++++++++++++++++++++++ .github/ISSUE_TEMPLATE.md | 37 ++++++++ .github/PULL_REQUEST_TEMPLATE.md | 32 +++++++ README.markdown | 17 +++- 4 files changed, 234 insertions(+), 4 deletions(-) create mode 100644 .github/CONTRIBUTING.md create mode 100644 .github/ISSUE_TEMPLATE.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000000..a7d2bd4d70 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,152 @@ +# 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?](#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. diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md new file mode 100644 index 0000000000..b93045731b --- /dev/null +++ b/.github/ISSUE_TEMPLATE.md @@ -0,0 +1,37 @@ + + +### System information + +Type | Version/Name + --- | --- +Distribution Name | +Distribution Version | +Linux Kernel | +Architecture | +ZFS Version | +SPL Version | + + +### Describe the problem you're observing + +### Describe how to reproduce the problem + +### Include any warning/errors/backtraces from the system logs + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000000..7c11a46da6 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,32 @@ + + +### Description + + +### Motivation and Context + + + +### How Has This Been Tested? + + + + + +### Types of changes + +- [ ] 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: + + +- [ ] 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. diff --git a/README.markdown b/README.markdown index 3fc88a0e5f..fd2ca8c866 100644 --- a/README.markdown +++ b/README.markdown @@ -1,10 +1,19 @@ -Native ZFS for Linux! - +

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: +be found at [our site](http://zfsonlinux.org/). + +# Contribute & Develop +We have a separate document with [contribution guidelines](./.github/CONTRIBUTING.md). \ No newline at end of file