updates to README about Git and contributing

1 files changed, 89 insertions, 14 deletions

diff --git a/debian/README.Debian b/debian/README.Debian
index 4cc3e0c7..52e556c9 100644
--- a/debian/README.Debian
+++ b/debian/README.Debian
@@ -5,7 +5,7 @@ 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://svn.debian.org/wsvn/pkg-mdadm/mdadm/trunk/debian/README.Debian?op=file&rev=0&sc=0
+  http://git.debian.org/?p=pkg-mdadm/mdadm.gita=blob;f=debian/README.Debian;hb=HEAD
 
 Upgrading and the configuration file
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -62,26 +62,101 @@ Further documents of interest:
 Upstream
 ~~~~~~~~
 For completeness: The upstream repository is available from
-  http://neil.brown.name/git?p=mdadm
   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 in SVN on alioth.debian.org. To obtain the source:
+The package is maintained with Git and published on git.debian.org. To obtain
+the source:
 
-  svn://svn.debian.org/svn/pkg-mdadm/mdadm/trunk
-  svn+ssh://<username>@svn.debian.org/svn/pkg-mdadm/mdadm/trunk
+  git clone git://git.debian.org/git/pkg-mdadm/mdadm
 
-The second form is for developers with the intention to contribute. If you
-want to join the mdadm effort, please talk to me.
+You can browse the repository here:
+  http://git.debian.org/?p=pkg-mdadm/mdadm
 
-Since the SVN repository only store the ./debian directory, you need the
-upstream tarball as well. I suggest using svn-buildpackage.
-
-Please do not forget to tag new releases.
+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 .
 
- -- martin f. krafft <madduck@debian.org>  Fri, 07 Jul 2006 10:55:42 +0200
-
-$Id$
+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'
+# the next two are not needed but ensure that git does not send patches to
+# your own email address.
+git config sendemail.signedoffcc false
+git config sendemail.suppressfrom true
+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