1 Building topgit for Debian
2 --------------------------
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.
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
13 1. Cloning the repository
14 ~~~~~~~~~~~~~~~~~~~~~~~~~
15 Cloning a TopGit repository requires an additional step to normal Git cloning:
17 1. git clone ssh://git.debian.org/git/collab-maint/topgit.git
19 3. tg remote --populate origin
21 You can also use the debcheckout tool from the devscripts package:
25 which will do all the above for you automatically.
29 The following branches are in use in the package:
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
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.
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
50 The following are the steps required to add a feature branch/patch:
52 1. tg create features/new-feature upstream
54 tg create debian/new-debian-stuff master
56 2. edit .topmsg and make the subject line be a short description, optionally
57 add a longer description to the body
59 3. git add .topmsg && git commit -m'create branch features/new-feature'
61 3. Obtaining the upstream tarball
62 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
63 The upstream tarball for $VERSION can be obtained using pristine-tar:
65 pristine-tar checkout ../topgit_$VERSION.orig.tar.gz
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:
72 -include /usr/share/topgit/topgit.mk
74 This will provide the tg-export target, which will create a quilt series of
75 all TopGit branches in the current repository.
77 You can also set the variable TG_BRANCHES to a space- or comma-separated list
78 (but not comma and space) of feature branches to export, e.g.:
80 TG_BRANCH := branch1,branch2
81 TG_BRANCH := 'branch3 branch4 branch 5'
83 (The TopGit package actually uses the local version of the file)
85 When you are ready to build, you check out the build branch, recreate
86 debian/patches, commit, build, test, upload, tag:
90 3. ./debian/rules tg-export
91 4. git add debian/patches
92 5. git commit -m'preparing 0.5-1'
93 6. build, test, upload, tag ('debian/topgit-0.5-1')
95 TODO: add a debian/NEWS entry to get people to switch to using this approach.
97 5. Importing a new upstream version
98 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
99 To import a new upstream, update the remote, merge the tag you want to merge
100 into the master branch, ideally together with an update to debian/changelog,
101 then update all TopGit branches:
104 2. git checkout master
105 3. git merge topgit-0.5
107 Now proceed as in the next step.
109 6. Making changes to the master branch
110 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
111 If you make changes to the master branch (the "debianisation" branch), follow
115 2. for every branch that is prefixed with 'D' in the output:
116 git checkout $BRANCH && tg update
118 7. Building an upstream tarball
119 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
120 Until upstream provides official tarballs, the following can be used to create
123 1. git checkout topgit-0.5
124 2. git archive --prefix=$(git describe HEAD)/ --verbose HEAD \
125 | gzip -9 > ../$(git describe HEAD | sed s,-,_,).orig.tar.gz
126 3. pristine-tar commit ../$(git describe HEAD | sed s,-,_,).orig.tar.gz \
128 4. git checkout master
130 All comments and suggestions are welcome, especially those pertaining to
131 auto-generating debian/changelog from commit logs.
133 -- martin f. krafft <madduck@debian.org> Mon, 11 Aug 2008 17:32:48 -0300