mdadm for Debian
================

To RAID5 or not to RAID5
~~~~~~~~~~~~~~~~~~~~~~~~
See http://www.miracleas.com/BAARF/BAARF2.html . The package maintainer could
not possibly come up with so much emotion over such a technical topic.

See also the RAID5_versus_RAID10.txt.gz document included with this package.

Further reading
~~~~~~~~~~~~~~~
The documentation for the kernel md driver is included in
/usr/share/doc/mdadm/md.txt.gz. In addition, the md(4) manpage provides
valuable information about the applicable concepts. Do read those!

Further documents of interest:
  - Linux-RAID reference Wiki:
      http://linux-raid.osdl.org
  - Linux software RAID HOWTO:
      http://tldp.org/HOWTO/Software-RAID-HOWTO.html
  - linux-raid mailing list info:
      http://vger.kernel.org/vger-lists.html#linux-raid
  - linux-raid mailing list FAQ:
      http://www.faqs.org/contrib/linux-raid/

Upstream
~~~~~~~~
For completeness: The upstream repository is available from
  git clone git://neil.brown.name/mdadm

You can browse Neil's repository here:
  http://neil.brown.name/git?p=mdadm

You can also clone from Debian's Git repository, where upstream's code is in
the 'upstream' branch:
  git://git.debian.org/git/pkg-mdadm/mdadm

Reporting bugs
~~~~~~~~~~~~~~
For reporting bugs, please use the reportbug tool, as it collects useful
information about the system where you're experiencing the problem.

If the system is another, please include the output of
/usr/share/bug/mdadm/scripts with your report.

If you are turning to the linux-raid@vger.kernel.org mailing list because you
already know that the issue is with the md kernel driver and certainly not
Debian-specific, please also include the output of
/usr/share/bug/mdadm/scripts.

In general, report bugs against the mdadm Debian package, using reportbug.
I am happy to route reports to where they belong.

Debian package maintenance
~~~~~~~~~~~~~~~~~~~~~~~~~~
The package is maintained with Git and published on git.debian.org. To obtain
the source:

  git clone git://git.debian.org/git/pkg-mdadm/mdadm

You can browse the repository here:
  http://git.debian.org/?p=pkg-mdadm/mdadm

If you want to join the mdadm effort, please send me an email. I'll be very
glad for any help I get.

There are things to do listed in debian/TODO.

You might also be interested in the following document, which explains how
package maintenance of mdadm was migrated from SVN to Git:
  http://blog.madduck.net/debian/2007.10.07_converting-a-package-to-git

Patches
~~~~~~~
The best way to submit patches is with git-format-patch, as outlined in the
following. If this is too complicated for you, please feel free to make
normal diffs, or contact me for assistance if you'd like to learn how to use
Git.

Please try to follow the guidelines outlined in
  http://repo.or.cz/w/git.git?a=blob;f=Documentation/SubmittingPatches;hb=HEAD

First, the setup, which you only have to do once on each machine you work with:

# leave out --global if you want to set your identity only for mdadm
git config --global user.name 'your name'
git config --global user.email 'your@email.address'
git clone git://git.debian.org/git/pkg-mdadm/mdadm.git

To prepare the actual patch, do the following:

git pull
git checkout -b some-name-identifying-my-work
while not finished:
  // if resuming after a while, maybe update your branch:
  git rebase master
  // edit files
  git add files
  git commit
  ...
end

After you've brought your change to a state where you want to submit it, please
squash it into logical single commits. If you only made one change, then this
will do:

git checkout -b temp-squash master
git merge --squash some-name-identifying-my-work
git commit // ... remove the "Squashed commit of the following:" leader
git format-patch -M -s master
// now inspect the files this created in $PWD
// when you're ready to submit, do:
git send-email --to your@email.address
// check that it's okay when it arrives
git send-email --to pkg-mdadm-devel@lists.alioth.debian.org

For multiple logical changes, cherry-pick or squash-merge every commit
belonging to a change to the integration branch and then commit it.

Also, read the git-send-email manpage in case you're submitting multiple
logical changes, in case you want to thread them.

The manpage also includes information about adding a prologue message explaining your patch, or how to insert it into an existing
thread (in-reply-to).

 -- martin f. krafft <madduck@debian.org>  Tue, 16 Oct 2007 18:12:13 +0100
