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. Please
  10 make sure to have the latest version of TopGit (>= 0.3) installed before
  11 trying this:
  12
  13 1. Cloning the repository
  14 ~~~~~~~~~~~~~~~~~~~~~~~~~
  15 Cloning a TopGit repository requires an additional step to normal Git cloning:
  16
  17 1. git clone ssh://git.debian.org/git/collab-maint/topgit.git
  18 2. cd topgit
  19 3. tg remote --populate origin
  20
  21 Branches in use
  22 '''''''''''''''
  23 The following branches are in use in the package:
  24
  25 - upstream: tracks the upstream Git repository
  26 - fixes/*: patches fixing problems with upstream
  27 - features/*: patches providing new features, targetted upstream
  28 - master: the main Debianisation branch
  29 - debian/*: Debian-specific patches
  30
  31 upstream and master are regular Git branches, while the others are TopGit
  32 branches. The reason why master is not a TopGit branch itself is so that it's
  33 possible to export all TopGit-managed branches into the quilt series, without
  34 having to make an exception for master.
  35
  36 2. Developing a new feature
  37 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  38 If you want to develop a new feature (or bug fix), first consider whether the
  39 patch is intended to go upstream or is a Debian-specific change. Choose the
  40 namespace accordingly and base it off upstream or master respectively. If the
  41 patch depends on another patch, obviously base it off the respective TopGit
  42 branch.
  43
  44 The following are the steps required to add a feature branch/patch:
  45
  46 1. tg create features/new-feature upstream
  47    - or -
  48    tg create debian/new-debian-stuff master
  49
  50 2. edit .topmsg and make the subject line be a short description, optionally
  51    add a longer description to the body
  52
  53 3. git add .topmsg && git commit -m'create branch features/new-feature'
  54
  55 3. Obtaining the upstream tarball
  56 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  57 The upstream tarball for $VERSION can be obtained using pristine-tar:
  58
  59   pristine-tar checkout ../topgit_$VERSION.orig.tar.gz
  60
  61 4. Building the package
  62 ~~~~~~~~~~~~~~~~~~~~~~~
  63 To build the package, you check out the build branch, recreate debian/patches,
  64 commit, build, test, upload, tag:
  65
  66  1. tg create stage-0.4-1 debian/locations
  67  2. git commit -m'staging 0.4-1'
  68  3. tg export --quilt debian/patches.new
  69  4. rm debian/patches.new/stage-*
  70  5. sed -i '/^stage-/d' debian/patches.new/series
  71  6. git checkout build && git rm -r debian/patches
  72  7. mv debian/patches.new debian/patches && git add debian/patches
  73  8. git commit -m'preparing 0.4-1'
  74  9. build, test, upload, tag ('debian/topgit-0.4-1')
  75 10. tg delete stage-0.4-1
  76
  77 This process is still very cumbersome and needs to be improved, ideally within
  78 TopGit.
  79
  80 5. Importing a new upstream version
  81 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  82 To import a new upstream, update the remote, merge the tag you want to merge
  83 into the master branch, ideally together with an update to debian/changelog,
  84 then update all TopGit branches:
  85
  86 1. git remote update
  87 2. git checkout master
  88 3. git merge topgit-0.4
  89
  90 Now proceed as in the next step.
  91
  92 6. Making changes to the master branch
  93 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  94 If you make changes to the master branch (the "debianisation" branch), follow
  95 this procedure:
  96
  97 1. tg summary
  98 2. for every branch that is prefixed with 'D' in the output:
  99      git checkout $BRANCH && tg update
 100 3. git checkout build && git merge master
 101
 102 7. Building an upstream tarball
 103 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 104 Until upstream provides official tarballs, the following can be used to create
 105 them for Debian:
 106
 107 1. git checkout topgit-0.4
 108 2. git archive --prefix=$(git describe HEAD)/ --verbose HEAD \
 109     | gzip -9 > ../$(git describe HEAD | sed s,-,_,).orig.tar.gz
 110 3. pristine-tar commit ../$(git describe HEAD | sed s,-,_,).orig.tar.gz \
 111     HEAD
 112 4. git checkout master
 113
 114 All comments and suggestions are welcome, especially those pertaining to
 115 auto-generating debian/changelog from commit logs.
 116
 117  -- martin f. krafft <madduck@debian.org>  Mon, 11 Aug 2008 17:32:48 -0300