path: root/
diff options
authorDavid Sterba <>2016-11-10 18:31:53 +0100
committerDavid Sterba <>2016-11-23 11:07:05 +0100
commitd8f93ce802c31dde2b936d0626b636dc070e118b (patch)
treeea9b151c434a5646c5487fbb4ad7e55e312acf09 /
parent776cd164b73092ec559a47080ff44aa22bad97a1 (diff)
btrfs-progs: Update README and other docs
Signed-off-by: David Sterba <>
Diffstat (limited to '')
1 files changed, 54 insertions, 9 deletions
diff --git a/ b/
index 13a2c838..e5e3f29f 100644
--- a/
+++ b/
@@ -1,4 +1,4 @@
-Btrfs-progs [![build status](](
+Btrfs-progs [![build status](]( [![coverity status](](
Userspace utilities to manage btrfs filesystems.
@@ -14,28 +14,73 @@ This repository hosts following utilities:
* **btrfs** &mdash; the main administration tool ([manual page](
* **mkfs.btrfs** &mdash; utility to create the filesystem ([manual page](
-See INSTALL for build instructions.
+See INSTALL for build instructions and [tests/](tests/ for
+testing information.
Release cycle
The major version releases are time-based and follow the cycle of the linux
kernel releases. The cycle usually takes 2 months. A minor version releases may
-happen in the meantime if there are queued bug fixes or minor useful
+happen in the meantime if there are bug fixes or minor useful improvements
+The release tags are signed with a GPG key ID `F2B4 1200 C54E FB30 380C 1756 C565 D5F9 D76D 583B`,
+release tarballs are hosted at [](
+See file [CHANGES](CHANGES) or [changelogs on wiki](
+Reporting bugs
+There are several ways, each has its own specifics and audience that can give
+feedback or work on a fix.
+* []( -- (requires
+ registration), set the product to Filesystems and component Btrfs, please put
+ 'btrfs-progs' into the subject so it's clear that it's not a kernel bug
+ report
+* to the mailing list ** -- (not required to
+ subscribe), beware that the mail might get overlooked in other traffic
+* [github issue tracker](
+* IRC ( #btrfs) -- good for discussions eg. if a bug is already
+ known, but reports could miss developers' attention
The patch submissions, development or general discussions take place at
-** mailinglist, subsciption not required.
+** mailinglist, subsciption is not required to post.
+The GitHub pull requests will not be accepted directly, the preferred way is to
+send patches to the mailinglist instead. You can link to a branch in any git
+repository if the mails do not make it to the mailinglist or just for
+convenience (makes it easier to test).
+The development model of btrfs-progs shares a lot with the kernel model. The
+github way is different in some ways. We, the upstream community, expect that
+the patches meet some criteria (often lacking in github contributions):
+* **one logical change per patch**: eg. not mixing bugfixes, cleanups, features
+ etc., sometimes it's not clear and will be usually pointed out during reviews
+* proper **subject line**: eg. prefix with _btrfs-progs: subpart, ..._ ,
+ descriptive yet not too long, see `git log --oneline` for some inspiration
+* proper **changelog**: the changelogs are often missing or lacking explanation _why_
+ the change was made, or _how_ is something broken, _what_ are user-visible
+ effects of the bug or the fix, _how_ does an improvement help or the intended
+ _usecase_
+* the **Signed-off-by** line: this documents who authored the change, you can read
+ more about the _The Developer's Certificate of Origin_ [here (chapter 11)](
+**Exceptions**: documentation fixes or updates do not need much explanation so
+sticking to the above rules is not necessary. Github pull requests are OK.
-* [Wiki with more information](
-* [Btrfs-progs changelogs](
-* [wiki/FAQ](
+* [wiki/Developer's FAQ]('s_FAQ)
* [wiki/Getting started](
* [wiki/TODO](
-* [wiki/Developer's FAQ]('s_FAQ)
+* [Btrfs-progs changelogs](
+* [wiki/FAQ](
+* [Wiki with more information](