chiark / gitweb /
Merge branch 'master' into refs/top-bases/debian/locations
[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.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.3-1 debian/locations
67  2. git commit -m'staging 0.3-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.3-1'
74  9. build, test, upload, tag ('debian/topgit-0.3-1')
75 10. tg delete stage-0.3-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, pull it into the upstream branch, merge upstream
83 into the master branch, ideally together with an update to debian/changelog,
84 then update all TopGit branches:
85
86 1. git checkout upstream
87 2. git pull
88 3. git checkout master
89 4. git merge upstream
90
91 Now proceed as in the next step.
92
93 6. Making changes to the master branch
94 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
95 If you make changes to the master branch (the "debianisation" branch), follow
96 this procedure:
97
98 1. tg summary
99 2. for every branch that is prefixed with 'D' in the output:
100      git checkout $BRANCH && tg update
101 3. git checkout build && git merge master
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 archive --prefix=$(git describe upstream)/ --verbose upstream \
109     | gzip -9 > ../$(git describe upstream | sed s,-,_,).orig.tar.gz
110 2. pristine-tar commit ../$(git describe upstream | sed s,-,_,).orig.tar.gz \
111     upstream
112
113 All comments and suggestions are welcome, especially those pertaining to
114 auto-generating debian/changelog from commit logs.
115
116  -- martin f. krafft <madduck@debian.org>  Mon, 11 Aug 2008 17:32:48 -0300