britney2-ubuntu/doc/short-intro-to-migrations.rst

A short introduction to migrations
==================================

This is a technical introduction to how britney
handles migrations.  Being an introduction, it deliberately
oversimplifies certain things at the expense of accuracy.
It also covers common migration issues and how to fix
them in :doc:`solutions-to-common-policy-issues`.

The document is primarily aimed at contributors for
distributions that want to understand the basics of
britney and its migration rules.

The documentation also aspires to be a general purpose document
for britney that is applicable for multiple distributions.
However, it does reference distribution-specific practises in
some examples to prevent the documentation from becoming too
abstract.  Furthermore, the document assumes familiarity with
Debian-based distribution practises and terminology (such as
"suites" and "source package").

A high level overview of britney and migrations
-----------------------------------------------

The purpose of britney is to (semi-)automatically select
a number of migration items from a series of source suites
(e.g. Debian unstable) that are ready to migrate to
the target suite (e.g. Debian testing).

The definition of "ready" can be summarized as satisfying all
of the following points:

 1. The migration items pass a number of policies for the target
    suite.  Most of these policies are basically that the
    migration items do not regress on selected QA checks.

    * An item satisfying this part is called a `valid candiate`.

 2. Installability will not regress as a result of
    migrating the migration items.

    * An item that (also) satisfies this part will be selected
      for migration.

The keyword in both points being *regress*.  If a package has an
existing issue in the target suite, the item including a new version
of that package is generally allowed to migrate if it has the same
issue (as it is not a regression).

This only leaves the definition of a migration items.  They come
in several variants defined in the next section.

Migration items
---------------

Internally, britney groups packages into migration items based on a
few rules.  There are several kinds of migration items and this
document will only describe the source migration item.

   A source migration item is one upload of a source package, with
   associated binary packages once built.

Once a new version of a source package appears in the source suite,
britney will track it with a source migration item.  As the
binary packages are built and uploaded, they will be included into the
migration item and various QA checks/policies will be applied to the
item.

Once britney deems the item ready, it will attempt to
migrate the item (i.e. source with its binaries) to the
target suite.


As implied earlier, there are several other migration types,
not covered in this document.  They deal with cases like removals,
rebuilds of existing binaries, etc.

Migration phase 1: Policies / Excuses
-------------------------------------

To begin with, britney will apply a number of policies to
all migration items.  Each policy will rate each migration
item and the combined results will be added into one of
britney's output documents known as the "excuses" (exists in
an HTML and a YAML variant).  A migration item that passes all
applicable policies will be labelled as a `valid candidate` in
the excuses and continue to the next phase.


The policies gives exactly one verdict to each item, some of
these verdicts are:

 * The item passes the policy.
 * The policy is waiting for test suites before providing a
   pass/fail result (temporary failure).
 * The item fails the policy and the failure is believed to
   be "permanent" (given no external changes).
 * The item does not pass the policy, but britney has
   insufficient information to determine if the failure is
   persistent or not.

It is important to note that all verdicts are based on the current
data that britney has access to.  This mean that without any change
to the items themselves:

 1. Items that passed originally may fail in a later britney run.

 2. Likewise, items may go from a "permanent failure" to a pass.

This can be seen in the following example case:

 1. A new version of package is uploaded.

    * Britney processes the package and concludes that there no blocking bugs,
      so the package passes the bug policy.

 2. Then before it migrates, someone files a blocking bug against
    the new version.

    * Britney reprocesses the package and now concludes it has a regression in
      the bug policy (i.e. the policy verdict goes from "pass" to "permanent fail").

 3. The bug is examined and it is determined that the bug also affects the
    version in the target suite.  The bug tracker is updated to reflect this.

    * Britney reprocesses the package again and now concludes there is a blocking
      bug, but it is not a regression (since it also affects the target suite).
      This means the policy verdict now go from "fail" to "pass".

This is also applicable to e.g. the piuparts policy, where if the test is
rescheduled on the piuparts side and the result changes as a result of that.

Finally, the people running the britney instance can overrule any
policy by applying a britney hint (see :ref:`hints` for more details), if they deem it
necessary.  One caveat here is that not all policies can be overridden
directly and some will require the "ignore all policies"-hint (known
as the `force`-hint).

Since most policies are defined based on regressions,
a hinted migration generally implies that the problem will not
prevent future migrations for newer versions of the same source
package (assuming that the problem is deterministic).

Migration phase 2: Installability regression testing
----------------------------------------------------

For the migration items that pass the previous phase, britney
will do a test migration to see if anything becomes uninstallable.
This is a more expensive test to ensure the migration does not cause
installability regressions.

The status of this phase is *not* included in the excuses.  To debug
problems here, the britney log file has to be examined.  This requires
a bit more technical insight as it has not been polished as much as
the excuses.

Confirming a migration
^^^^^^^^^^^^^^^^^^^^^^

To start with; if a migration is accepted and "committed" (i.e. it will not
be rolled back), britney will include in a line starting with ``final:`` like
in this example::

    Apparently successful
    final: -cwltool,-libtest-redisserver-perl,-pinfo,-webdis,hol88
    start: 41+0: a-4:i-27:a-1:a-1:a-1:m-0:m-3:m-1:p-1:s-2
     orig: 41+0: a-4:i-27:a-1:a-1:a-1:m-0:m-3:m-1:p-1:s-2
      end: 41+0: a-4:i-27:a-1:a-1:a-1:m-0:m-3:m-1:p-1:s-2
    SUCCESS (182/177)

The above example is a regular migration run where 4 source removal migration
items and one source migration item where accepted (those listed on the
``final:`` line). The rest of the information are various statistical counters
which are useful for other purposes beyond the scope of this document.

When debugging a migration for an item that passed the previous phase, if the
item appears on a ``final:`` line like that, then it is migrated.  That is, the
problem is most likely that the britney run crashes later or the britney's
output is not committed to the archive (for reasons outside britney's control).

On the flip side, if the migration item of interest does *not* appear in a
final line, then the migration was rejected (or rolled back).

Reminder: Migration items generally use the name of the source package.  There
are exceptions to that "rule" (but they are not common cases covered by this
document).

Debugging failed migration attempts
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Start by confirming that the migration item was not accepted (as described
in the above section).  If the migration item does not appear on a ``final:`` line,
then we need to debug the actual migration attempts.  Migration attempts look
something like this::

    trying: -webdis
    accepted: -webdis
       ori: 41+0: a-4:i-27:a-1:a-1:a-1:m-0:m-3:m-1:p-1:s-2
       pre: 41+0: a-4:i-27:a-1:a-1:a-1:m-0:m-3:m-1:p-1:s-2
       now: 41+0: a-4:i-27:a-1:a-1:a-1:m-0:m-3:m-1:p-1:s-2
       all: -pinfo -webdis
    [...]
    trying: libaws
    skipped: libaws (0, 165, 11)
        got: 45+0: a-4:i-27:a-5:a-1:a-1:m-0:m-3:m-1:p-1:s-2
        * arm64: libaws-bin, libaws17.2.2017, libaws3.3.2.2-dev, liblog4ada3-dev
    [...]
    Trying easy from autohinter: asis/2017-1 dh-ada-library/6.12 [...]
    start: 41+0: a-4:i-27:a-1:a-1:a-1:m-0:m-3:m-1:p-1:s-2
    orig: 41+0: a-4:i-27:a-1:a-1:a-1:m-0:m-3:m-1:p-1:s-2
    easy: 261+0: a-26:i-49:a-23:a-23:a-23:m-22:m-25:m-23:p-23:s-24
        * amd64: asis-programs, libasis2017, libasis2017-dev, libaws-bin, [...]
        * i386: asis-programs, libasis2017, libasis2017-dev, libaws-bin, [...]
        * arm64: asis-programs, libasis2017, libasis2017-dev, libaws-bin, [...]
        * armel: asis-programs, libasis2017, libasis2017-dev, libaws-bin, [...]
    [...]
    FAILED

This example has one succeeding migration (``-webdis``) and one failing
(``libaws``) plus finally a failed ``easy``-hint with several packages.
Both of the two first are "single item" migrations (i.e. the attempt only
includes a single item in isolation).  However, Britney can do multi-item
migrations (even outside hints).

Please keep in mind that items can attempted multiple times and accepted in a
later attempt.  It is not always immediately obvious, which attempt is better
for debugging.  When in doubt, it is *usually* easiest to look at the attempt
with the least amount of new uninstallable packages.

In the libaws example, a total of 4 binary packages become
uninstallable on the architecture ``arm64``.  Here is the output again
with this information high lighted::

    migration item(s) being attempted
            vvvvvv
    trying: libaws
    skipped: libaws (0, 165, 11)
        got: 45+0: a-4:i-27:a-5:a-1:a-1:m-0:m-3:m-1:p-1:s-2
        * arm64: libaws-bin, libaws17.2.2017, libaws3.3.2.2-dev, liblog4ada3-dev
          ^^^^^  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
          |||||        The binary packages becoming uninstallable (here 4)
          Affected architecture (here "arm64")

Please note that britney is lazy and will often reject an item after proving
that there is a regression on a single architecture.  So in the above example,
we are not actually sure whether this problem is architecture specific.  For
`easy`-hints, the information is presented slightly different::

    Trying easy from autohinter: asis/2017-1 dh-ada-library/6.12 [...]
                                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                    migration item(s) being attempted

    [... several lines of statistics from start, before and after ...]
        * amd64: asis-programs, libasis2017, libasis2017-dev, libaws-bin, [...]
          ^^^^^  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
          |||||        The binary packages becoming uninstallable on amd64
          Affected architecture (here "amd64")

        * i386: asis-programs, libasis2017, libasis2017-dev, libaws-bin, [...]
          ^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
          |||||       The binary packages becoming uninstallable on i386
          Affected architecture (here "i386")
    [... more architectures with binary packages becoming uninstallable ...]


While this tells us what britney tried to migrate and what would break (become
uninstallable) as a result, it is not very helpful at explaining *why*
things break.  If there are few broken packages, it is often a question of
looking for ``Breaks``-relations or ``Depends``-relations with upper bounds on
versions / on old packages being removed.  Alternatively, there are also tools
like ``dose-debcheck``, which attempts to analyse and explain problems like this.