--- /dev/null
+Building topgit for Debian
+--------------------------
+
+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:
+
+1. Branches in use
+~~~~~~~~~~~~~~~~~~
+The following branches are in use in the package:
+
+- upstream: tracks the upstream Git repository
+- fixes/*: patches fixing problems with upstream
+- features/*: patches providing new features, targetted upstream
+- master: the main Debianisation branch
+- debian/*: Debian-specific patches
+
+upstream and master are regular Git branches, while the others are TopGit
+branches. The reason why master is not a TopGit branch itself is so that it's
+possible to export all TopGit-managed branches into the quilt series, without
+having to make an exception for master.
+
+2. Developing a new feature
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you want to develop a new feature (or bug fix), first consider whether the
+patch is intended to go upstream or is a Debian-specific change. Choose the
+namespace accordingly and base it off upstream or master respectively. If the
+patch depends on another patch, obviously base it off the respective TopGit
+branch.
+
+The following are the steps required to add a feature branch/patch:
+
+1. tg create features/new-feature upstream
+ - or -
+ tg create debian/new-debian-stuff master
+
+2. edit .topmsg and make the subject line be a short description, optionally
+ add a longer description to the body
+
+3. git add .topmsg && git commit -m'create branch features/new-feature'
+
+3. Obtaining the upstream tarball
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The upstream tarball for $VERSION can be obtained using pristine-tar:
+
+ pristine-tar checkout ../topgit_$VERSION.orig.tar.gz
+
+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.
+
+5. Importing a new upstream version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To import a new upstream, pull it into the upstream branch, merge upstream
+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:
+ git checkout $BRANCH && tg update
+
+6. 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
+
+All comments and suggestions are welcome, especially those pertaining to
+auto-generating debian/changelog from commit logs.
+
+ -- martin f. krafft <madduck@debian.org> Mon, 11 Aug 2008 17:32:48 -0300
~ian / topgit.git / commitdiff