debian/HOWTO-tg2quilt

   1 Using TopGit to generate quilt series for Debian packaging
   2 ----------------------------------------------------------
   3
   4 You have been referred to this document probably because a source package you
   5 are working on uses TopGit to generate a quilt series to encapsulate
   6 differences between upstream and the source code used for the Debian package.
   7
   8 Please make sure that you have a recent version of TopGit (>= 0.5) installed
   9 before trying any of this.
  10
  11 Where appropriate, the examples use the topgit package itself to illustrate
  12 the use. I trust you to be able to make the appropriate amendments for your
  13 situation.
  14
  15 1. Cloning the repository
  16 ~~~~~~~~~~~~~~~~~~~~~~~~~
  17 Cloning a TopGit repository requires an additional step to normal Git cloning:
  18
  19 1. git clone ssh://git.debian.org/git/collab-maint/topgit.git
  20 2. cd topgit
  21 3. tg remote --populate origin
  22
  23 You can also use the debcheckout tool from the devscripts package:
  24
  25   debcheckout topgit
  26
  27 which will do all the above for you automatically.
  28
  29 Branches in use
  30 '''''''''''''''
  31 The following branches are in use in the topgit package. You are free to
  32 deviate from this set for the package you are working on, but then please
  33 document it accordingly in your README.source.
  34
  35 - upstream: tracks the upstream Git repository
  36 - fixes/*: patches fixing problems with upstream
  37 - features/*: patches providing new features, targetted upstream
  38 - master: the main Debianisation branch
  39 - debian/*: Debian-specific patches
  40
  41 upstream and master are regular Git branches, while the others are TopGit
  42 branches. The reason why master is not a TopGit branch itself is so that it's
  43 possible to export all TopGit-managed branches into the quilt series, without
  44 having to make an exception for master.
  45
  46 2. Developing a new feature
  47 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  48 If you want to develop a new feature (or bug fix), first consider whether the
  49 patch is intended to go upstream or is a Debian-specific change. Choose the
  50 namespace accordingly and base it off upstream or master respectively. If the
  51 patch depends on another patch, obviously base it off the respective TopGit
  52 branch.
  53
  54 The following are the steps required to add a feature branch/patch:
  55
  56 1. tg create features/new-feature upstream
  57    - or -
  58    tg create debian/new-debian-stuff master
  59
  60 2. edit .topmsg and make the subject line be a short description, optionally
  61    add a longer description to the body
  62
  63 3. git add .topmsg && git commit
  64
  65 3. Obtaining the upstream tarball
  66 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  67 The upstream tarball for the topgit package $VERSION can be obtained using
  68 pristine-tar:
  69
  70   pristine-tar checkout ../topgit_$VERSION.orig.tar.gz
  71
  72 4. Building the package
  73 ~~~~~~~~~~~~~~~~~~~~~~~
  74 Building the package is trivial, thanks to the inclusion of the tg2quilt.mk
  75 snippet at the top of debian/rules.
  76
  77 Unless you set the TG_BRANCHES variable before the include statement (or when
  78 you invoke debian/rules (or make), tg2quilt will simply export all TopGit
  79 branches into the quilt series. You can set the variable TG_BRANCHES to
  80 a space- or comma-separated list (but not comma and space) of feature branches
  81 to export, e.g.:
  82
  83   TG_BRANCHES := branch1,branch2
  84   TG_BRANCHES := 'branch3 branch4 branch 5'
  85
  86 Building the package requires no additional steps over other Debian packages.
  87
  88 Since it is currently not possible to access TopGit branches for previous
  89 versions of a package (#500656), it is a good idea to maintain a build branch,
  90 into which you merge the master (Debianisation) branch whenever making a new
  91 release, and where you simply track the contents of the debian/patches
  92 directory. This can conveniently become the branch from which you build:
  93
  94 1. git checkout build
  95 2. git merge master
  96 3. ./debian/rules tg-cleanexport
  97 4. git add debian/patches
  98 5. git commit -m'preparing $VERSION'
  99 6. build, test, upload, tag ('debian/topgit-$VERSION')
 100
 101 TODO: add a debian/NEWS entry to get people to switch to using this approach.
 102
 103 5. Importing a new upstream version
 104 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 105 To import a new upstream, update the remote, merge the tag you want to merge
 106 into the master branch, ideally together with an update to debian/changelog,
 107 then update all TopGit branches:
 108
 109 1. git remote update
 110 2. git checkout master
 111 3. git merge <new-upstream-tag>
 112
 113 Now proceed as in the next step.
 114
 115 6. Making changes to the master branch
 116 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 117 If you make changes to the master branch (the "debianisation" branch), follow
 118 this procedure:
 119
 120 1. tg summary
 121 2. for every branch that is prefixed with 'D' in the output:
 122      git checkout $BRANCH && tg update
 123
 124 7. Building an upstream tarball
 125 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 126 If you are using pristine-tar, the follopwing can be used to commit an
 127 upstream tarball to the repository. It makes sense to rename it according to
 128 the Debian-standard package_version.orig.tar.gz convention first.
 129
 130 1. pristine-tar commit ../topgit_$VERSION.orig.tar.gz <upstream-tag>
 131
 132 If upstream does not provide tarballs, you can create the orig.tar.gz file and
 133 commit is as follows:
 134
 135 1. git checkout topgit-$VERSION
 136 2. git archive --prefix=$(git describe HEAD)/ --verbose HEAD \
 137     | gzip -9 > ../$(git describe HEAD | sed s,-,_,).orig.tar.gz
 138 3. pristine-tar commit ../$(git describe HEAD | sed s,-,_,).orig.tar.gz \
 139     HEAD
 140 4. git checkout master
 141
 142
 143
 144 All comments and suggestions are welcome, especially those pertaining to
 145 auto-generating debian/changelog from commit logs.
 146
 147  -- martin f. krafft <madduck@debian.org>  Wed, 19 Nov 2008 15:16:03 +0100