summaryrefslogtreecommitdiffstats
path: root/wiki/src/contribute/release_process/tails-installer.mdwn
blob: 5c9a0f8f7907fcb8c03e9428a26ac8243de6e611 (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
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
[[!meta title="Releasing tails-installer"]]

[[!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. Thus, from version 4.x on, our fork has been renamed to
tails-installer.

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 Jessie.

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
targeted 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. `4.*` as currently used on
  Tails/Jessie 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. Make sure to check them out when setting up the repository
  for the first time.
* For Ubuntu, we want to support the current Ubuntu version (currently `yakkety`), the
  upcoming version (currently `zesty`), and the current LTS (currently
  `xenial`).
  We do not maintain any Git branches related to Ubuntu releases, as simply the changelog
  entries are modified.

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 `4.*` upstream release, before it lands into
`feature/stretch` and in turn into a new `5.*` 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 `4.14`, based on the
upstream branch you are building the Debian package for. Adjust and
export:

    export NEW_UPSTREAM_VERSION=4.replace_me
    export UPSTREAM_DEV_BRANCH=master
    export PKG_NAME=tails-installer

<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" \
           "$PKG_NAME.pot" ; done \
       ) && \
       git commit po -m 'Update POT and PO files.' && \
    git tag \
       -s "${PKG_NAME}_${NEW_UPSTREAM_VERSION}" \
       -m "Releasing Tails Installer $NEW_UPSTREAM_VERSION" && \
    git push --tags origin "$UPSTREAM_DEV_BRANCH"

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

### Generate a new upstream tarball

    mkdir -p ../tarballs && \
    git archive \
       --prefix="${PKG_NAME}-${NEW_UPSTREAM_VERSION}/" \
       --output="../tarballs/${PKG_NAME}_${NEW_UPSTREAM_VERSION}.tar.gz" \
       "$UPSTREAM_DEV_BRANCH"

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

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

Checkout the packaging branch:

	export PKG_NAME=tails-installer
	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/${PKG_NAME}_${NEW_UPSTREAM_VERSION}.tar.gz && \
	gbp import-orig \
	   --upstream-vcs-tag="${PKG_NAME}_$NEW_UPSTREAM_VERSION" \
	   ../tarballs/${PKG_NAME}_${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,).*,),')

Git-Dch: Ignore
"

Make sure that the working environment is clean:

    git clean -fdx

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 --tags origin "$UPSTREAM_BRANCH" \
                    "$PACKAGING_BRANCH" \
                    pristine-tar

If you are a member of the Debian pkg-privacy team
--------------------------------------------------

Add the remote:

    git remote add debian ssh://git.debian.org/git/pkg-privacy/packages/tails-installer.git

Then push:

    git push --tags debian "$UPSTREAM_BRANCH" \
                    "$PACKAGING_BRANCH" \
                    pristine-tar

Never force push! If `git push` fails you may have to merge back in
e.g. `debian/pristine-tag` into your local `pristine-tar` and push
again. Also push it to `origin`, in that case.

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

Upload a package to our Ubuntu PPA
----------------------------------

Team members are allowed to upload a package to our Ubuntu PPA:
<https://launchpad.net/~tails-team/+archive/ubuntu/tails-installer>

You'll need to configure the dput tool to upload to the PPA and put into
`$HOME/.dput.cf` (adjust to use your Launchpad ID):

    [ppa-tails-installer]
    fqdn = ppa.launchpad.net
    method = ftp
    incoming = ~tails-team/ubuntu/tails-installer/
    login = your_launchpad_id
    allow_unsigned_uploads = 0

* checkout the `debian/sid` branch
  to build a package for the next Ubuntu release or checkout the
  `debian/jessie-backports` branch to build a package for the
  current Ubuntu version or current LTS.
* bump version to `4.3+dfsg-0ubuntu1~$codename` using `dch -i`
  where `$codename` is the name of the target Ubuntu distribution.
* if it does not exist, rebuild the .orig.tar.gz of the latest version
  from pristine-tar (use the latest git log entry to find the version):
  `pristine-tar checkout ../tails-installer_4.4.6+dfsg.orig.tar.gz`
* build a source only package using `debuild -i -uc -us -sa -S`
  Once the package has been built, a `.changes` file will be created in
  pbuilder's configured destination directory.
* test the package (piuparts, Lintian, etc.)
* sign the corresponding source.changes file
  `debsign ../tails-installer_$NEW_UPSTREAM_RELEASE-xxx_source.changes`
  Replace "xxx" with the correct version information.
  The signature should be made with a key which is registered
  at Launchpad as being part of the Tails team.
* Upload to the PPA:
  `dput ppa-tails-installer ../tails-installer_$NEW_UPSTREAM_RELEASE+xxx_source.changes`

You will receive an email informing you if the upload was really successful
or if it contained any errors. On success, you should now revert your changes on the
Debian branch using `git reset HEAD --hard`.

Quality assurance for Debian and Ubuntu packages
------------------------------------------------

    Scenario: Installing Tails to a pristine USB drive
      Given I have started Debian
      And I have a Tails ISO image
      When I install the tails-installer package
      And I plug USB drive "install"
      And I ask Tails Installer to install my Tails ISO image to USB drive "install"
      Then my Tails ISO image is installed on USB drive "install"

    Scenario: Upgrading an old Tails USB installation from an ISO image
      Given I have started Debian
      And I have a Tails ISO image
      When I install the tails-installer package
      And I plug USB drive "upgrade" that has an old Tails installed
      And I ask Tails installer to upgrade USB drive "upgrade" with my Tails ISO image
      Then my Tails ISO image is installed on USB drive "upgrade"