Our APT repositories

(full) time-based snapshots of the
upstream APT repositories we use, so that we can use frozen
versions thereof when needed;

(partial) tagged snapshots of upstream
APT repositories we need, so that one can rebuild a released ISO in
the future, and we keep the corresponding source code around.

Snapshots and branches

Here we discuss what APT snapshots of upstream repositories are used
when building a Tails ISO image. This a is function of the branch we
build from, as well as if we are building an ISO that is meant to be released (i.e.
whether there is a tag in Git corresponding the last entry in
debian/changelog).

Note: when we say "building an ISO from the B branch" below, we only
refer to the base branch, i.e. B is encoded in config/base_branch.
Hence such statements also refers to topic branches with B as base
branch.

Building an ISO from the devel branch always uses the freshest set
of APT repository snapshots available. Resolving what's the set of
freshest APT repository snapshots is done at the beginning of the
build (auto/config,
auto/scripts/apt-mirror), so that the entire build
uses the exact same state of these
repositories. This is needed for reproducible builds, and has a nice
side effect: so long, Hashsum mismatch, and thanks for the fish.

When building an ISO from the branch used to prepare the next major
release (testing):

outside of the freeze period: the testing branch is not used;

freeze period: at freeze time, the RM encodes in the Git
testing branch the set of APT repository snapshots (via their
serial numbers) that shall be used during the freeze; the only
exception is security.debian.org, for which we always use our
latest snapshot;

at release time: when building from a tagged branch, similarly to
what we do for our
custom APT repository, instead
of using time-based APT repository snapshots, we use snapshots
labeled with the Git tag (note that this is not needed, strictly speaking,
as the APT sources used at Tails runtime will anyway be the
official (and not frozen) Debian ones; this is mostly needed for
legal purposes (this allows to distribute for a long
time the source packages needed to build a given Tails ISO image),
and it will be useful when we want to be able to reproduce a given
Tails ISO build).

When building an ISO from the branch used to prepare the next
point-release (stable) we use the same time-based snapshots that
were used to prepare the latest Tails release, except:

we use our latest snapshot of security.debian.org;

at release time: when building from a tagged branch, similarly to
what we do for our
custom APT repository, instead
of using time-based APT repository snapshots, we use snapshots
labeled with the Git tag.

Design notes

Miscellaneous

We want to have reproducible builds some day. Therefore, the APT
sources.list shipped in the ISO must be stable across rebuilds from
the same release Git tag.

APT sources used inside Tails

A running Tails' APT must be pointed at the official, live Debian
archive, and not to a Tails-specific and already obsolete snapshot.

Say kedit is a package shipped in Debian, but not in Tails. Then,
when run inside Tails, apt install kedit must fetch kedit from
current Debian, as opposed to installing it from a Tails-specific, and
generally obsolete, snapshot of the Debian APT repository.

Upgrading to a new snapshot

In other words: bumping, in Git, the pointers to the set of snapshots
that shall be used by a given branch.

Let's use, as an example of a situation in which we might want to do
that, upgrading to a new Debian point-release.

With this design:

devel gets them automatically because it closely tracks the
Debian archive;

for release branches (stable, testing): on a case-by-case
basis, depending on the respective Debian/Tails release schedule
timing, we can choose whether to switch to using a new snapshot of
the Debian archive for the next release. Note that this can be done
via a topic-branch since this information is encoded in Git. If we
choose not to manually pick the point release, which is the default
if we don't act at all, then:

testing will start using the new Debian point-release as soon
as it is unfrozen, that is as soon as it has been used to release
a new major version of Tails;

stable will start using the new Debian point-release once
a testing branch that uses that point-release is merged into
stable.