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

Please make sure you read into /usr/share/doc/mdadm/NEWS.Debian.gz and the
documents listed under "further reading" a little later in this file.

The latest version of this document is available here:
  http://git.debian.org/?p=pkg-mdadm/mdadm.gita=blob;f=debian/README.Debian;hb=HEAD

Autostarting devices
~~~~~~~~~~~~~~~~~~~~
The mdadm.conf file controls which devices are to be started automatically by
mdadm during boot, and various other parameters about how they are to be started.
The file can also contain some control parameters for the mdadm monitor daemon.
See mdadm.conf(5) for more information.

Note: this only applies to modular kernels. If you use a monolithic kernel,
you can control which devices are started automatically by changing the
partition type: 0xfd for autostart, 0x83 to prevent autostart. mdadm does not
actually care about the partition type, only the kernel does.

Common recipes
~~~~~~~~~~~~~~
Check /usr/share/doc/mdadm/README.recipes.gz for some simple examples of how
to do the most common stuff with mdadm.

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.

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
