Building topgit for Debian
--------------------------
-The topgit source package uses quilt to apply and remove its patches. Please
+The topgit source package uses quilt to apply and remove its patches. Please
refer to /usr/share/doc/quilt/README.source for information about how to use
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:
+itself. While subject to change, this currently happens as follows. Please
+make sure to have the latest version of TopGit (>= 0.5) installed before
+trying this:
-1. Branches in use
-~~~~~~~~~~~~~~~~~~
+1. Cloning the repository
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Cloning a TopGit repository requires an additional step to normal Git cloning:
+
+1. git clone ssh://git.debian.org/git/collab-maint/topgit.git
+2. cd topgit
+3. tg remote --populate origin
+
+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
+'''''''''''''''
The following branches are in use in the package:
- upstream: tracks the upstream Git repository
4. Building the package
~~~~~~~~~~~~~~~~~~~~~~~
-To build the package, you check out the build branch, recreate debian/patches,
-commit, build, test, upload, tag:
-
- 1. git checkout build && git rm -r debian/patches
- 2. tg create stage-0.2-1 fixes/destdir debian/locations ...
- 3. git commit -m'staging 0.2-1'
- 4. tg export --quilt debian/patches
- 5. rm debian/patches/stage-*
- 6. sed -i '/^stage-/d' debian/patches/series
- 7. git checkout -f build && git add debian/patches
- 8. git commit -m'preparing 0.2-1'
- 9. build, test, upload, tag ('debian/topgit-0.2-1')
-10. tg delete stage-0.2-1
-
-This process is still very cumbersome and needs to be improved, ideally within
-TopGit.
+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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-To import a new upstream, pull it into the upstream branch, merge upstream
+To import a new upstream, update the remote, merge the tag you want to merge
into the master branch, ideally together with an update to debian/changelog,
then update all TopGit branches:
-1. git checkout upstream
-2. git pull
-3. git checkout master
-4. git merge upstream
-5. tg summary
-6. for every branch that is prefixed with 'D' in the output:
+1. git remote update
+2. git checkout master
+3. git merge topgit-0.5
+
+Now proceed as in the next step.
+
+6. Making changes to the master branch
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you make changes to the master branch (the "debianisation" branch), follow
+this procedure:
+
+1. tg summary
+2. for every branch that is prefixed with 'D' in the output:
git checkout $BRANCH && tg update
-6. Building an upstream tarball
+7. Building an upstream tarball
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Until upstream provides official tarballs, the following can be used to create
them for Debian:
-1. git archive --prefix=$(git describe upstream)/ --verbose upstream \
- | gzip -9 > ../$(git describe upstream | sed s,-,_,).orig.tar.gz
-2. pristine-tar commit ../$(git describe upstream | sed s,-,_,).orig.tar.gz \
- upstream
+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 \
+ HEAD
+4. git checkout master
All comments and suggestions are welcome, especially those pertaining to
auto-generating debian/changelog from commit logs.
~ian / topgit.git / blobdiff