summaryrefslogtreecommitdiffstats
path: root/wiki/src/contribute/release_process/liveusb-creator.mdwn
blob: 1f5c1f49012e4102f34be5101b5c07408e9b91e3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
[[!meta title="Releasing liveusb-creator"]]

[[!toc levels=3]]

The big picture
===============

Upstream
--------

For this package, "upstream" means, from a Debian packaging
point-of-view, the state of our upstream branches. Let's not pretend we
have not forked liveusb-creator, and admit we are now upstream for our
own version.

The `master` branch must always be the one that targets current Tails.
That's what we have always done, and right
now `master` is indeed targeting Wheezy.

But that's not enough, since we also need to put releases out with code
that works on current Debian testing/sid. Thus, we maintain several upstream
release branches in parallel, each with their own major version number:

 * for releases that target Wheezy:
   * version = `3.*`
   * tag = `tails-installer_3.*`
 * for work and releases that target Jessie (and, as long as compatible,
   that target testing/sid as well):
   * branch = feature/jessie (that's what we've been doing so far)
   * version = `4.*`
   * tag = `tails-installer_4.*`

Once we can't support both Jessie and testing/sid with the same
codebase anymore, we'll fork a new upstream release branch that targets Stretch,
it'll be called feature/stretch, use version `5.*`, etc.

Packaging
---------

We're using [DEP-14 conventions](http://dep.debian.net/deps/dep14/),
except for our `master` branch which is used for upstream development
targetted at current Tails, as said above. More specifically:

* The `pristine-tar` branch contains the binary delta between DFSG-freed
  tarballs and the corresponding tag. It's automatically maintained by
  `gbp import-orig`.
* The `debian/sid` branch is used to build the package that we upload to
  Debian unstable. The tags on this branch are called `debian/$package_version`,
  which is the default when creating them with
  `gbp buildpackage --git-sign-tags --git-tag-only`;
  in practice this is something like `debian/4.0+dfsg-1`.
* The `debian/$codename-backports` branch is used to prepare packages
  that we upload to the official backports repository for Debian `$codename`.
  E.g. here we want to have `debian/jessie-backports` soon after the initially
  uploaded package reaches Debian testing. The tags on this branch are also called
  `debian/$package_version`. In practice this is something like
  `debian/4.0+dfsg-1~bpo8+1`.
* The `tails/$codename` branch is used to prepare packages that we upload
  to the Tails APT repo, but not to Debian -- e.g. `3.*` as currently used on
  Tails/Wheezy will never be uploaded to Debian.
* Additionally, we use `tails/$feature` branches for other Tails-specific packaging branches.
* The `upstream/3.x+dfsg`, `upstream/4.x+dfsg`, etc. branches are what we tell `gbp`
  to use as its "upstream" branch.

Topic branches
--------------

In practice, it's expected that Tails contributors submit bugfix and
feature branches forked off master, because they want them part of next
Tails release. Hence, it will happen that code lands into master first,
and in turn into a new `3.*` upstream release, before it lands into
`feature/jessie` and in turn into a new `4.*` upstream release.

For how to package topic branches (`bugfix/*` and `feature/*`), see
[[the dedicated page|topic_branch]].

Workflow
========

Release a new upstream version
------------------------------

<a id="upstream-prepare"></a>

### Prepare the environment

The new upstream version should be something like `3.14`, based on the
upstream branch you are building the Debian package for. Adjust and
export:

    export NEW_UPSTREAM_VERSION=3.replace_me
    export UPSTREAM_DEV_BRANCH=master

<a id="upstream-tag"></a>

### Tag the new version

    git checkout "$UPSTREAM_DEV_BRANCH" && \
    ./setup.py build && \
       (cd po && \
           for po in *.po ; do msgmerge --update "$po" \
           liveusb-creator.pot ; done \
       ) && \
       git commit po -m 'Update POT and PO files.' && \
    git tag \
       -s "tails-installer_$NEW_UPSTREAM_VERSION" \
       -m "Releasing Tails Installer $NEW_UPSTREAM_VERSION" && \
    git push origin "$UPSTREAM_DEV_BRANCH" && \
    git push origin --tags

<a id="upstream-tarball"></a>

### Generate a new upstream tarball

    mkdir -p ../tarballs && \
    git archive \
       --prefix="liveusb-creator-$NEW_UPSTREAM_VERSION/" \
       --output="../tarballs/liveusb-creator_$NEW_UPSTREAM_VERSION.tar.gz" \
       "$UPSTREAM_DEV_BRANCH"

<a id="tails-package"></a>

Update the Debian package for Tails
-----------------------------------

Checkout the packaging branch, that would be `tails/wheezy` or `tails/jessie`,
for example:

	export PACKAGING_BRANCH=tails/jessie
	git checkout "$PACKAGING_BRANCH"

Verify that `debian/gbp.conf` references the correct upstream and Debian (packaging) branches,
and that `pristine-tar` usage is enabled, e.g.:

	[DEFAULT]
	upstream-branch = upstream/4.x+dfsg
	debian-branch = tails/jessie
	pristine-tar = True

Extract the upstream and packaging branch from gbp.conf:

	export UPSTREAM_BRANCH=`gbp config buildpackage.upstream-branch | sed -r -e 's,.*=,,'`

Create a DFSG-compatible tarball from the previously created Git
archive and reimport it into the source tree. This merges, into the
`debian-branch` specified in `gbp.conf`, not only the commit that
imported the current DFSG free upstream tarball into the
`upstream-branch`, but also the corresponding upstream Git history:

	mk-origtargz \
	   -C ../tarballs \
	   --version "$NEW_UPSTREAM_VERSION+dfsg" \
	   --copy \
	   ../tarballs/liveusb-creator_$NEW_UPSTREAM_VERSION.tar.gz && \
	gbp import-orig \
	   --upstream-vcs-tag="tails-installer_$NEW_UPSTREAM_VERSION" \
	   ../tarballs/liveusb-creator_$NEW_UPSTREAM_VERSION+dfsg.orig.tar.gz

Update `debian/changelog`:

    gbp dch && dch -e

In there, set the appropriate:

* version number, such as `4.3+dfsg-0tails1`; in particular, note that
  the Debian revision starts with `-0` for any package meant for the
  Tails APT repository, while the first package that will be uploaded
  to Debian will have `-1`;
* target release name.

Commit the changelog:

    git commit debian/changelog -m "$(head -n 1 debian/changelog | sed -e 's,).*,),')"

Build a new Tails package (use a i386 chroot that matches the target distribution):

    gbp buildpackage

Add a signed tag to the Git repository and push the changes:

    gbp buildpackage --git-tag-only --git-sign-tags && \
    git push origin "$UPSTREAM_BRANCH" \
                    "$PACKAGING_BRANCH" \
                    pristine-tar && \
    git push origin --tags

Add the Debian package to Tails
-------------------------------

Sign the package:

    debsign $CHANGES_FILE

Upload:

    dupload --to tails $CHANGES_FILE

Update the Debian package
-------------------------

This assumes that the latest upstream release has been imported into
a Tails packaging branch (e.g. `tails/jessie`) already.

And then, a maintainer of `tails-installer` in Debian updates the
package in sid accordingly, for example:

* check out the `debian/sid` branch
* merge the `tails/jessie` branch
* bump version to `4.3+dfsg-1`
* build, test and upload to sid
* have gbp create a `debian/4.3+dfsg-1` tag
* push the Debian packaging branch (`debian/sid`) and the new tag

Example for a backport to Jessie:

* check out the `debian/jessie-backports` branch
* merge the `debian/sid` branch
* `dch --bpo` to bump version to `4.3+dfsg-1~bpo8+1`
* build, test and upload to jessie-backports
* have gbp create a `debian/4.3+dfsg-1_bpo8+1` tag
* push the Debian packaging branch (`debian/jessie-backports`) and the new tag