fix detection of topgit repo

[topgit.git] / debian / README.source

diff --git a/debian/README.source b/debian/README.source
index e6c6f6ce587503aa974dee781bbc0b04acac411d..7ae068f179dfb8c8ab30719d79b4eceb64c4b075 100644 (file)
--- a/debian/README.source
+++ b/debian/README.source
@@ -7,7 +7,7 @@ quilt for source packages.
 
 The quilt series is, however, generated from the Git repository, using TopGit
 itself. While subject to change, this currently happens as follows. Please
-make sure to have the latest version of TopGit (>= 0.3) installed before
+make sure to have the latest version of TopGit (>= 0.5) installed before
 trying this:
 
 1. Cloning the repository
@@ -18,7 +18,11 @@ Cloning a TopGit repository requires an additional step to normal Git cloning:
 2. cd topgit
 3. tg remote --populate origin
 
-TODO: debcheckout support
+You can also use the debcheckout tool from the devscripts package:
+
+  debcheckout topgit
+
+which will do all the above for you automatically.
 
 Branches in use
 '''''''''''''''
@@ -62,25 +66,34 @@ The upstream tarball for $VERSION can be obtained using pristine-tar:
 
 4. Building the package
 ~~~~~~~~~~~~~~~~~~~~~~~
-To build the package, you check out the build branch, recreate debian/patches,
-commit, build, test, upload, tag:
-
- 1. tg create stage-0.4-1 debian/locations
- 2. git commit -m'staging 0.4-1'
- 3. tg export --quilt debian/patches.new
- 4. rm debian/patches.new/stage-*
- 5. sed -i '/^stage-/d' debian/patches.new/series
- 6. git checkout build && git rm -r debian/patches
- 7. mv debian/patches.new debian/patches && git add debian/patches
- 8. git commit -m'preparing 0.4-1'
- 9. build, test, upload, tag ('debian/topgit-0.4-1')
-10. tg delete stage-0.4-1
-
-This process is still very cumbersome and needs to be improved, ideally within
-TopGit.
-
-TODO: provide Makefile snippet for the above to prevent useless duplication (#501991)
-TODO: rewrite to use tg-export -b, which will be fixed in TopGit 0.5 (#500273)
+To build the package, you are encouraged to include the TopGit make snippet at
+the top of debian/rules:
+
+  -include /usr/share/topgit/topgit.mk
+
+This will provide the tg-export target, which will create a quilt series of
+all TopGit branches in the current repository.
+
+You can also set the variable TG_BRANCHES before the inclusion to a space- or
+comma-separated list (but not comma and space) of feature branches to export,
+e.g.:
+
+  TG_BRANCHES := branch1,branch2
+  TG_BRANCHES := 'branch3 branch4 branch 5'
+
+(The TopGit package actually uses the local version of the file)
+
+When you are ready to build, you check out the build branch, recreate
+debian/patches, commit, build, test, upload, tag:
+
+1. git checkout build
+2. git merge master
+3. ./debian/rules tg-export
+4. git add debian/patches
+5. git commit -m'preparing 0.5-1'
+6. build, test, upload, tag ('debian/topgit-0.5-1')
+
+TODO: add a debian/NEWS entry to get people to switch to using this approach.
 
 5. Importing a new upstream version
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -90,7 +103,7 @@ then update all TopGit branches:
 
 1. git remote update
 2. git checkout master
-3. git merge topgit-0.4
+3. git merge topgit-0.5
 
 Now proceed as in the next step.
 
@@ -102,14 +115,13 @@ this procedure:
 1. tg summary
 2. for every branch that is prefixed with 'D' in the output:
      git checkout $BRANCH && tg update
-3. git checkout build && git merge master
 
 7. Building an upstream tarball
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Until upstream provides official tarballs, the following can be used to create
 them for Debian:
 
-1. git checkout topgit-0.4
+1. git checkout topgit-0.5
 2. git archive --prefix=$(git describe HEAD)/ --verbose HEAD \
     | gzip -9 > ../$(git describe HEAD | sed s,-,_,).orig.tar.gz
 3. pristine-tar commit ../$(git describe HEAD | sed s,-,_,).orig.tar.gz \