wiki/src/contribute/APT_repository.mdwn

   1 [[!toc levels=2]]
   2
   3 To avoid cluttering our main Git repository with Debian source and
   4 binary packages, we have set an APT repository up.
   5
   6 [[!toc levels=2]]
   7
   8 Overview
   9 ========
  10
  11 We use one single APT repository hosting multiple *suites*:
  12
  13 * We have a (read-only) suite for every past release: `0.9`,
  14   `0.10.1`, etc.
  15 * We have a suite for each *main* branch: `stable`, `testing`, `devel`
  16 * We have a suite for each *topic* branch: `bugfix/*`, `feature/*`.
  17   **Important note**: the APT suite corresponding to a given Git topic
  18   branch contains *only* the packages this branch adds to the tag or
  19   *main* branch it diverged from.
  20 * We also have a less formal `unstable` suite, that should not be used
  21   by any Tails git branch; it can be used as hosting space for other
  22   packaging work we might do, e.g. acting as upstream or
  23   Debian maintainers.
  24 * We also have a `debomatic-squeeze-backports-mozilla` suite, used
  25   (hopefully temporarily) import build-deps for our web browser, that
  26   are not available elsewhere (anymore). This suite is used by the
  27   `squeeze-backports-mozilla` chroot in our [[contribute/Debian
  28   package builder]].
  29 * We also have a `builder-wheezy` suite, used to provide additional
  30   packages needed on a Wheezy system to build Tails.
  31
  32 The suite(s) to use as sources for APT, during the build and inside
  33 the resulting system, are determined at Tails build time
  34 (`auto/config`). See details in the *Build system* section bellow.
  35
  36 We manage our APT repository with
  37 [reprepro](http://mirrorer.alioth.debian.org/).
  38
  39 The Puppet modules used to manage this part of our infrastructure are
  40 listed on our [[contribute/Git]] page.
  41
  42 Basically, a cronjob fetches and scans the Tails Git repository every
  43 few minutes, detects new branches, and accordingly:
  44
  45 - generates `conf/distributions`
  46 - generates `conf/incoming`
  47 - create new suites in the APT repository
  48
  49 Build system
  50 ============
  51
  52 The build system adds the relevant APT sources:
  53
  54 * if the version in `debian/changelog` was released already (i.e.
  55   a matching tag exists), then add the suite corresponding to this
  56   release (e.g. `0.10` or `0.10.1`);
  57 * else, if building from the `testing` branch, add the `testing` suite
  58 * else, if building from the `experimental` branch, add the `experimental` suite
  59 * else, if building from the `devel` branch, add its own suite
  60
  61 Also, if we're building from a bugfix or feature branch, add its
  62 own suite.
  63
  64 SSH access
  65 ==========
  66
  67 One must configure their SSH client to connect to the APT server:
  68
  69         Host incoming.deb.tails.boum.org
  70                 Port 3003
  71
  72 HTTP access
  73 ===========
  74
  75 This is the http:// public APT repository used at Tails
  76 build time. The `tails::reprepro` Puppet class sets nginx up to
  77 serve that.
  78
  79 Workflow
  80 ========
  81
  82 Creating a new branch
  83 ---------------------
  84
  85 Push your branch to Git and wait a few minutes for the new APT suite
  86 to appear.
  87
  88 Importing a new package
  89 -----------------------
  90
  91 ### Building a package
  92
  93 Make sure the `Distribution:` field in your `.changes` file matches
  94 the suite you want the package to land in (e.g.
  95 pass `--changes-option=-DDistribution=feature-torbrowser` to
  96 pdebuild's `--debbuildopts`).
  97
  98 Make sure to have the `.changes` file include the original source
  99 archive (`.orig.tar.{gz,bz2,xz}`) if it is not already in our APT
 100 repository; this can be done by passing `-sa` to pdebuild's
 101 `--debbuildopts`.
 102
 103 ### Configuring an upload tool
 104
 105 #### Configuring dupload
 106
 107 Add this configuration snippet to your `dupload` configuration:
 108
 109         $config::cfg{'tails'} = {
 110                 fqdn => "incoming.deb.tails.boum.org",
 111                 method => "scp",
 112                 login => "reprepro",
 113                 incoming => "/srv/reprepro/incoming/",
 114                 dinstall_runs => 1,
 115         };
 116
 117 #### Confuguring dput
 118
 119 Add this to `.dput.cf`:
 120
 121     [tails]
 122     fqdn            = incoming.deb.tails.boum.org
 123     method          = scp
 124     login           = reprepro
 125     incoming        = /srv/reprepro/incoming/
 126     run_dinstall    = 0
 127
 128
 129 ### Uploading and importing process
 130
 131 Carefully prepare and build your package. Usual precautions, (Lintian
 132 etc.) apply.
 133
 134 Carefully check the `.changes` file (especially the `Distribution`
 135 control field, and the included files list; the former can be fixed
 136 with the `changestool(1)` command, from [[!debpkg reprepro]]).
 137
 138 Sign the `.changes` file with a key that is in the uploaders list:
 139
 140         $ debsign $CHANGES_FILE
 141
 142 Upload the files to the incoming queue:
 143
 144         $ dupload --to tails $CHANGES_FILE
 145
 146 reprepro will automatically notice the new files and import them into
 147 the suite specified in your `.changes` file.
 148
 149 Check the result:
 150
 151         $ ssh reprepro@incoming.deb.tails.boum.org reprepro list $SUITE $PACKAGENAME
 152
 153 <a id="workflow-merge-topic-branch"></a>
 154
 155 Merging a topic branch
 156 ----------------------
 157
 158 When a Git *topic* branch is merged into a *main* branch, the
 159 corresponding operation must be done on the APT suites.
 160
 161 Example:
 162
 163         $ git checkout devel
 164         $ git merge feature/icedove
 165         $ ssh reprepro@incoming.deb.tails.boum.org \
 166              tails-merge-suite feature-icedove devel
 167         $ git push
 168
 169 (Note that unfortunately, contrary to what whoever with a Git
 170 background would guess, the reprepro operation called *pull* is not
 171 what we want: it pulls from *all* other suites into the ones specified
 172 on the command-line.)
 173
 174 <a id="workflow-merge-main-branch"></a>
 175
 176 Merging a main branch
 177 ----------------------
 178
 179 When a Git *main* branch (`devel`, `experimental`, `testing`,
 180 `stable`) is merged into another *main* branch, the corresponding
 181 operation must be done on the APT suites.
 182
 183 1. Save the list of packages currently present in the APT suite we
 184    want to merge *into*, e.g. `reprepro list experimental`.
 185 2. Make sure you are not going to overwrite newer packages with
 186    older ones.
 187 3. Merge the APT suites [[the same way as when we merge a topic
 188    branch|APT_repository#workflow-merge-topic-branch]].
 189 4. Make sure not to re-add, into the branch we merge into, any package
 190    that was removed from it, but still is in the branch we merge from:
 191    e.g. when merging `devel` into `experimental`, it may be that
 192    `experimental` had some packages removed (e.g. due to previously
 193    merging a topic branch into it, whose purpose is to *remove* custom
 194    packages). To this end, compare the resulting list of (package,
 195    version) in the `experimental` APT suite with the one saved before
 196    the merge (hint: use the `tails-diff-suites` script), check Git
 197    merges history if needed, apply common sense, and remove from
 198    `experimental` the packages that were removed from it a while ago,
 199    and were just erroneously re-added by the merge operation.
 200
 201 <a id="workflow-reset"></a>
 202
 203 Resetting a suite to the state of another one
 204 ---------------------------------------------
 205
 206    a. First, set some environment variables:
 207
 208         # the suite to reset
 209         OLD=testing
 210         # the final state it should be in
 211         NEW=devel
 212
 213    b. Then, empty the `OLD` suite:
 214
 215         ssh reprepro@incoming.deb.tails.boum.org \
 216               reprepro removematched $OLD '\*'
 217
 218    c. Finally, merge `NEW` into `OLD`
 219
 220         ssh reprepro@incoming.deb.tails.boum.org \
 221               tails-merge-suite $NEW $OLD
 222
 223 <a id="workflow-freeze"></a>
 224
 225 Freezing devel into testing
 226 ---------------------------
 227
 228 1. Merge `devel` branch into `testing` in Git
 229 2. (Manually) [[hard reset|APT_repository#workflow-reset]] the
 230    `testing` suite to the current state of the `devel` one.
 231
 232 <a id="workflow-post-tag"></a>
 233
 234 Tagging a new Tails release
 235 ---------------------------
 236
 237 Once the new release's Git tag is pushed, a cronjob should create
 238 a new APT suite on the APT repository's side within a few minutes.
 239 This new APT suite is called the same as the new release version.
 240 One may check it has appeared in `~reprepro/conf/distributions`.
 241
 242 Then, the APT suite corresponding to the branch that was used to
 243 prepare the release must be copied to the new empty APT suite that
 244 just appeared:
 245
 246 If this is a major release:
 247
 248         $ ssh reprepro@incoming.deb.tails.boum.org \
 249              tails-merge-suite testing $TAG
 250
 251 Else, if this is a point-release:
 252
 253         $ ssh reprepro@incoming.deb.tails.boum.org \
 254              tails-merge-suite stable $TAG
 255
 256 <a id="workflow-post-release"></a>
 257
 258 After a new Tails release is out
 259 --------------------------------
 260
 261 If you just put out a final release:
 262
 263 * [[merge `stable` or `testing` into
 264   `devel`|APT_repository#workflow-merge-main-branch]]
 265 * increment the version number in devel's `debian/changelog` to match
 266   the next major release, so that
 267   next builds from the `devel` branch do not use the APT suite meant
 268   for the last release
 269 * increment the version number in stable's `debian/changelog` to match
 270   the next point release, so that
 271   next builds from the `stable` branch do not use the APT suite meant
 272   for the last release
 273
 274 If you just released a RC:
 275
 276 * add a dummy changelog entry (for the upcoming, non-RC version) in
 277   the branch used for the release (`stable` or `testing`), so that the
 278   next builds from it do not use the APT suite meant for the RC
 279 * add a dummy changelog entry (for the release *after* the one you
 280   released a RC for) in the branch used for the release (`stable` or
 281   `testing`), so that the next builds from it do not use the APT suite
 282   meant for the RC
 283
 284 If the release was a major one, then [[reset the stable APT suite to
 285 the state of the testing one|APT_repository#workflow-reset]].
 286
 287 Giving access to a core developer
 288 ---------------------------------
 289
 290 1. Give SSH access to the `reprepro` user on the system that hosts
 291    reprepro (using the `ssh_authorized_key` Puppet resource).
 292 2. Import the developer's public GnuPG key into the `reprepro` user's
 293    GnuPG keyring -- should be doable using Puppet, some day
 294 3. Add the developer's OpenPGP key ID to `$reprepro_uploaders` in our
 295    `tails::reprepro` Puppet module. Deploy.
 296
 297 Contributing without privileged access
 298 --------------------------------------
 299
 300 Non-core developers without access to the "private" APT infrastructure
 301 would add the .deb they want to their Git branch as we have been
 302 doing until now, push the result on repo.or.cz or whatever... and at
 303 merge time, we would rewrite their history to remove the .deb, and
 304 import it into our APT repo.