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