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.5) 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 You can also use the debcheckout tool from the devscripts package:
  22
  23   debcheckout topgit
  24
  25 which will do all the above for you automatically.
  26
  27 Branches in use
  28 '''''''''''''''
  29 The following branches are in use in the package:
  30
  31 - upstream: tracks the upstream Git repository
  32 - fixes/*: patches fixing problems with upstream
  33 - features/*: patches providing new features, targetted upstream
  34 - master: the main Debianisation branch
  35 - debian/*: Debian-specific patches
  36
  37 upstream and master are regular Git branches, while the others are TopGit
  38 branches. The reason why master is not a TopGit branch itself is so that it's
  39 possible to export all TopGit-managed branches into the quilt series, without
  40 having to make an exception for master.
  41
  42 2. Developing a new feature
  43 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  44 If you want to develop a new feature (or bug fix), first consider whether the
  45 patch is intended to go upstream or is a Debian-specific change. Choose the
  46 namespace accordingly and base it off upstream or master respectively. If the
  47 patch depends on another patch, obviously base it off the respective TopGit
  48 branch.
  49
  50 The following are the steps required to add a feature branch/patch:
  51
  52 1. tg create features/new-feature upstream
  53    - or -
  54    tg create debian/new-debian-stuff master
  55
  56 2. edit .topmsg and make the subject line be a short description, optionally
  57    add a longer description to the body
  58
  59 3. git add .topmsg && git commit -m'create branch features/new-feature'
  60
  61 3. Obtaining the upstream tarball
  62 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  63 The upstream tarball for $VERSION can be obtained using pristine-tar:
  64
  65   pristine-tar checkout ../topgit_$VERSION.orig.tar.gz
  66
  67 4. Building the package
  68 ~~~~~~~~~~~~~~~~~~~~~~~
  69 To build the package, you are encouraged to include the TopGit make snippet at
  70 the top of debian/rules:
  71
  72   -include /usr/share/topgit/topgit.mk
  73
  74 This will provide the tg-export target, which will create a quilt series of
  75 all TopGit branches in the current repository.
  76
  77 You can also set the variable TG_BRANCHES before the inclusion to a space- or
  78 comma-separated list (but not comma and space) of feature branches to export,
  79 e.g.:
  80
  81   TG_BRANCHES := branch1,branch2
  82   TG_BRANCHES := 'branch3 branch4 branch 5'
  83
  84 (The TopGit package actually uses the local version of the file)
  85
  86 When you are ready to build, you check out the build branch, recreate
  87 debian/patches, commit, build, test, upload, tag:
  88
  89 1. git checkout build
  90 2. git merge master
  91 3. ./debian/rules tg-export
  92 4. git add debian/patches
  93 5. git commit -m'preparing 0.5-1'
  94 6. build, test, upload, tag ('debian/topgit-0.5-1')
  95
  96 TODO: add a debian/NEWS entry to get people to switch to using this approach.
  97
  98 5. Importing a new upstream version
  99 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 100 To import a new upstream, update the remote, merge the tag you want to merge
 101 into the master branch, ideally together with an update to debian/changelog,
 102 then update all TopGit branches:
 103
 104 1. git remote update
 105 2. git checkout master
 106 3. git merge topgit-0.5
 107
 108 Now proceed as in the next step.
 109
 110 6. Making changes to the master branch
 111 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 112 If you make changes to the master branch (the "debianisation" branch), follow
 113 this procedure:
 114
 115 1. tg summary
 116 2. for every branch that is prefixed with 'D' in the output:
 117      git checkout $BRANCH && tg update
 118
 119 7. Building an upstream tarball
 120 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 121 Until upstream provides official tarballs, the following can be used to create
 122 them for Debian:
 123
 124 1. git checkout topgit-0.5
 125 2. git archive --prefix=$(git describe HEAD)/ --verbose HEAD \
 126     | gzip -9 > ../$(git describe HEAD | sed s,-,_,).orig.tar.gz
 127 3. pristine-tar commit ../$(git describe HEAD | sed s,-,_,).orig.tar.gz \
 128     HEAD
 129 4. git checkout master
 130
 131 All comments and suggestions are welcome, especially those pertaining to
 132 auto-generating debian/changelog from commit logs.
 133
 134  -- martin f. krafft <madduck@debian.org>  Mon, 11 Aug 2008 17:32:48 -0300