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. Please
make sure to have the latest version of TopGit (>= 0.5) installed before
trying this:

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

TODO: debcheckout support

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 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 to a space- or comma-separated list
(but not comma and space) of feature branches to export, e.g.:

  TG_BRANCH := branch1,branch2
  TG_BRANCH := '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')

5. Importing a new upstream version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 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

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.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.

 -- martin f. krafft <madduck@debian.org>  Mon, 11 Aug 2008 17:32:48 -0300