Add suggestions by Frédéric Brin

1 files changed, 37 insertions, 21 deletions

diff --git a/development/debian_packages_in_git.mdwn b/development/debian_packages_in_git.mdwn
index d412b34..78b469f 100644
--- a/development/debian_packages_in_git.mdwn
+++ b/development/debian_packages_in_git.mdwn
@@ -1,13 +1,14 @@
 [[!toc]]
 
 # Keeping debian/patches on a patch-queue branch
-I'm keeping all patches for a Debian package that is maintained on branch *foo* on a patch-queue branch *patch-queue/foo* since:
+I'm keeping all patches for a Debian package that is maintained on branch *foo* on a patch-queue branch *patch-queue/foo*:
 
-* one can easily work with the unpatched (*foo*) and patched (*patch-queue/foo*) branches
-* patches can easily be dropped, added by modifying the patch-queue branch (no messing with *quilt add*, *dpatch-edit-patch*, *cdbs-edit-patch* or the like)
-* easy cherry-picking of patches for stable releases, etc.
-* easy forward porting of patches to new upstream versions by using *git rebase* on the *patch-queue/foo* branch (patches already applied upatream are detected automatically).
-* the generated patch in *debian/patches/* has all the necessary information to forward it upstream since it's auto generated via *git-format-patch*.
+* One can easily work with the unpatched (*foo*) and patched (*patch-queue/foo*) branches
+* One commit on the *patch-queue* branch represents exactly on patch in *debian/patches/*
+* Patches can easily be dropped, added by modifying the patch-queue branch (no messing with *quilt add*, *dpatch-edit-patch*, *cdbs-edit-patch* or the like)
+* Easy cherry-picking of patches for stable releases, etc.
+* Easy forward porting of patches to new upstream versions by using *git rebase* on the *patch-queue/foo* branch (patches already applied upstream are detected automatically).
+* The generated patch in *debian/patches/* has all the necessary information to forward it upstream since it's auto generated via *git-format-patch*.
 
 Disadvantage:
 
@@ -16,31 +17,44 @@ Disadvantage:
 ### Workflow:
 Assuming the Debian source package has it's patches in *debian/patches* and these are parseable by *git-quiltimport(1)*:
 
-* create *patch-queue* branch and import *debian/patches* onto it using [gbp-pq](http://honk.sigxcpu.org/projects/git-buildpackage/gbp-pq):
+* Create *patch-queue* branch and import *debian/patches* onto it using gbp-pq:
 
         cd $REPO
         gbp-pq import
-
-* work an patch-queue branch (add, remove, rebase, test)
-* switch back to master:
-
-        git checkout master
-
-* regenerate the patches in *debian/patches/* using [gbp-pq](http://honk.sigxcpu.org/projects/git-buildpackage/gbp-pq):
+* This will switch you to the patch-queue branch automatically. If you stared from *master* the patch-queue branch will be called *patch-queue/master*.
+* Now you can work on the patch-queue branch (add, remove, rebase, test) to get your patches into shape:
+    * To add what will later become a patch in *debian/patches/* simply make a commit. The first line of the commit message will become the patch name later. The following lines include the details of what the patch does.
+    * To remove or edit commits use *git rebase -i master*. The [git documentation][] explains how to work with git-rebase.
+* Regenerate the patches in *debian/patches/* using gbp-pq. This will switch you back to *master* and regenerate the patches using *git-format-patch(1)*:
 
         gbp-pq export
-
-* commit the result either by using *gbp-add-patch* or simply
+* Commit the result either by using *gbp-add-patch* or simply
 
         git commit -a debian/changelog
-
-* update *debian/changelog* (e.g. by running "git-dch -S -a")
-* build the package
-* after importing a new upstream version you can use the following commands to refresh *debian/patches*:
+* Update *debian/changelog* (e.g. by running "git-dch -S -a")
+* Build the package
+* After importing a new upstream version you can use the following commands to refresh *debian/patches*:
 
         gbp-pq rebase
         git checkout master
         gbp-pq export
+* If a package doesn't have any patches yet, these are the steps to add your first patch:
+
+    1. Launch an import, this will switch to the proper branch
+
+            gbp-pq import
+    2. Create your first patch:
+
+          * Edit files / Test
+          * Commit your changes using *git commit*
+    3. Back to the master branch, generate the Quilt patch set
+
+            git checkout master
+            gbp-pq export
+    4. Commit you first patch
+        
+            git add -a debian/patches/
+            git commit -m 'my first patch'
 
 ### Team maintenance
 The easiest way is to not push out any patch-queue/* branches at all. They can be recreated by any team member easily by using
@@ -68,7 +82,7 @@ Build and test...
     gbp-pq export
 
 # Cloning a repository
-If you use *gbp-clone* instead of *git clone* to clone a remote repository it will automatically set up the *debian*, *upstream* and *pristine-tar* branches for you. The [manual](http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.intro.html#GBP.REPOSITORY) explains the terminology.
+If you use *gbp-clone* instead of *git clone* to clone a remote repository it will automatically set up the *debian*, *upstream* and *pristine-tar* branches for you. The [manual][] explains the terminology.
 
 # Keeping a repository up to date
 After initially cloning with *gbp-clone* you can run *gbp-pull* to update your
@@ -113,3 +127,5 @@ and *gbp-cowbuilder-lenny* uses */usr/share/doc/git-buildpackage/examples/gbp-co
     ln -s /usr/share/doc/git-buildpackage/examples/gbp-cowbuilder-sid ~/bin/gbp-cowbuilder-lenny
 
 
+[git documentation]: http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#cleaning-up-history
+[manual]: http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.intro.html#GBP.REPOSITORY