1 files changed, 148 insertions, 0 deletions
diff --git a/debian/README.Debian b/debian/README.Debian
new file mode 100644
index 00000000..bfca8cb3
--- /dev/null
+++ b/debian/README.Debian
@@ -0,0 +1,148 @@
+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