debian/README.source

   1 Building topgit for Debian
   2 --------------------------
   3
   4 The topgit source package  uses quilt to apply and remove its patches. Please
   5 refer to /usr/share/doc/quilt/README.source for information about how to use
   6 quilt for source packages.
   7
   8 The quilt series is, however, generated from the Git repository, using TopGit
   9 itself. While subject to change, this currently happens as follows:
  10
  11 1. Branches in use
  12 ~~~~~~~~~~~~~~~~~~
  13 The following branches are in use in the package:
  14
  15 - upstream: tracks the upstream Git repository
  16 - fixes/*: patches fixing problems with upstream
  17 - features/*: patches providing new features, targetted upstream
  18 - master: the main Debianisation branch
  19 - debian/*: Debian-specific patches
  20
  21 upstream and master are regular Git branches, while the others are TopGit
  22 branches. The reason why master is not a TopGit branch itself is so that it's
  23 possible to export all TopGit-managed branches into the quilt series, without
  24 having to make an exception for master.
  25
  26 2. Developing a new feature
  27 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  28 If you want to develop a new feature (or bug fix), first consider whether the
  29 patch is intended to go upstream or is a Debian-specific change. Choose the
  30 namespace accordingly and base it off upstream or master respectively. If the
  31 patch depends on another patch, obviously base it off the respective TopGit
  32 branch.
  33
  34 The following are the steps required to add a feature branch/patch:
  35
  36 1. tg create features/new-feature upstream
  37    - or -
  38    tg create debian/new-debian-stuff master
  39
  40 2. edit .topmsg and make the subject line be a short description, optionally
  41    add a longer description to the body
  42
  43 3. git add .topmsg && git commit -m'create branch features/new-feature'
  44
  45 3. Obtaining the upstream tarball
  46 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  47 The upstream tarball for $VERSION can be obtained using pristine-tar:
  48
  49   pristine-tar checkout ../topgit_$VERSION.orig.tar.gz
  50
  51 4. Building the package
  52 ~~~~~~~~~~~~~~~~~~~~~~~
  53 To build the package, you check out the build branch, recreate debian/patches,
  54 commit, build, test, upload, tag:
  55
  56  1. git checkout build && git rm -r debian/patches
  57  2. tg create stage-0.2-1 fixes/destdir debian/locations ...
  58  3. git commit -m'staging 0.2-1'
  59  4. tg export --quilt debian/patches
  60  5. rm debian/patches/stage-*
  61  6. sed -i '/^stage-/d' debian/patches/series
  62  7. git checkout -f build && git add debian/patches
  63  8. git commit -m'preparing 0.2-1'
  64  9. build, test, upload, tag ('debian/topgit-0.2-1')
  65 10. tg delete stage-0.2-1
  66
  67 This process is still very cumbersome and needs to be improved, ideally within
  68 TopGit.
  69
  70 5. Importing a new upstream version
  71 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  72 To import a new upstream, pull it into the upstream branch, merge upstream
  73 into the master branch, ideally together with an update to debian/changelog,
  74 then update all TopGit branches:
  75
  76 1. git checkout upstream
  77 2. git pull
  78 3. git checkout master
  79 4. git merge upstream
  80 5. tg summary
  81 6. for every branch that is prefixed with 'D' in the output:
  82      git checkout $BRANCH && tg update
  83
  84 6. Building an upstream tarball
  85 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  86 Until upstream provides official tarballs, the following can be used to create
  87 them for Debian:
  88
  89 1. git archive --prefix=$(git describe upstream)/ --verbose upstream \
  90     | gzip -9 > ../$(git describe upstream | sed s,-,_,).orig.tar.gz
  91 2. pristine-tar commit ../$(git describe upstream | sed s,-,_,).orig.tar.gz \
  92     upstream
  93
  94 All comments and suggestions are welcome, especially those pertaining to
  95 auto-generating debian/changelog from commit logs.
  96
  97  -- martin f. krafft <madduck@debian.org>  Mon, 11 Aug 2008 17:32:48 -0300