diff --git a/doc/hints.md b/doc/hints.md new file mode 100644 index 0000000..fd9e6eb --- /dev/null +++ b/doc/hints.md @@ -0,0 +1,275 @@ +#! TITLE: Britney hints documentation +#! SUBTITLE: How to override the britney policies + +# Britney hints + +This document describes the "britney hints". These are basically +small instructions to britney. The vast majority of them involve +overriding a quality gating policy in britney. However, there are a +few hints that assist britney into finding solutions that she cannot +compute herself. + + +## Related configuration + +The configuration `HINTSDIR` determines which directory contains the +so called "hints files". This is complimented with the `HINTS_` +configurations that defines a "hint file" and the related hint +permissions for it. + +For each `HINTS_` configuration, britney will attempt to read +`/`. Note that she lowercases `` when looking +for the file. + + +Configuration example: + + HINTSDIR = /etc/britney2/hints + HINTS_ANNA = ALL + HINTS_JOHN = STANDARD + HINTS_FREEZE = block block-all block-udeb + HINTS_AUTO-REMOVALS = remove + +There is no fixed rules for how to use hints files. Though usually, +each person with permissions to give hints to Britney will have their +own hint file along with write permissions for that file. It can also +make sense to create hint files for "roles". Like in the above +example there are two human hints (anna and john) plus two non-human +hinters (freeze and auto-removals). + + +## Format of the hint file + +The hint file is a plain text file with line-based content. Empty and +whitespace-only lines are ignored. If the first (non-whitespace) +character is a `#`, then britney considers it a comment and ignores +it. However, other tooling may interpret these comments (as is the +case for e.g. some parts of the Debian infrastructure). + +The remaining lines are considered space-separated lists, where the +first element must be a known hint. The remaining elements will be +interpreted as its arguments. Britney generally warns on and then +discards unknown hints or hints with invalid arguments. + +The following are common types of arguments for hints: + + * Unversioned item, format: `` + * Versioned item, format: `/` + * Architecture-qualified versioned item: `//` + +Generally, for hints, all item names will be names of source packages. +Furthermore, some hints also accept a `-` before the item name. This +generally refers to the removal of said item rather than the migration +of the hint. + + +# Hints + +There are the following type of hints: + + * Policy overrides + * Migration selections (with or without overrides) + * Other + + +## Policy override hints + +The policy override hints are used to disable or tweak various +policies in Britney. Their effects are generally very precise ways of +accepting specific regressions or disabling various checks. + +Some of these items are built-in while others are related to specific +policies. In the latter case, they are only valid if the given policy +is enabled (as the policy registers them when it is enabled). + +### block-all `` + +Usually used during freezes to prevent migrations by default. + +The `` can be one of: + + * `source`: Blocks all source migrations. This is a superset of + `new-source`. + * `new-source`: Block source migrations if the given source is not + already in the target suite. (Side-effect: Removed packages will + not re-enter the taget suite automatically). + +All variants of these can be overruled by a valid `unblock`-hint. + +Note that this does not and cannot restrict architecture specific +migrations (e.g. binNMUs or first time builds for architectures). + +### block ``, block-udeb `` + +Prevent the items in the `` from migrating until the hint +is removed or overruled by the equivalent unblock hint (or a +`remove`-hint). All items in the `` must be unversioned +items and can be prefixed with `-` to prevent removal by built-in +policies. However, it will not prevent removals requested by a +`removal`-hint. + +The `block-udeb` is mainly intended for preventing accidental +migration of installer-related packages during the later stages of the +release cycle. + +Note that this does not and cannot restrict architecture specific +migrations (e.g. binNMUs or first time builds for architectures). + +### unblock ``, unblock-udeb `` + +Enable the items in `` to migrate by overriding `block`-, +`block-all`- or `block-udeb`-hints. The `unblock`-hint (often under +its synonym `approve`) is also used to approve migrations from source +suites that require approval. + +The items in `` must all be versioned items. + +The `unblock-udeb` is mainly intended for preventing accidental +migration of installer-related packages during the later stages of the +release cycle. + +The two types of block hint must be paired with their corresponding +unblock hint - i.e. an `unblock-udeb` does not override a `block`. + +### approve `` + +A synonym of `unblock`. The variant is generally used for approving +migrations from suites that require approvals. + +Aside from the tab-completion in the hint testing interface, which +will give different suggestions to `approve` and `unblock`, the rest +of britney will consider them identical. + +### age-days `` `` + +Set the length of time which the listed action items must have been in +unstable before they can be considered candidates. This may be used +to either lengthen or reduce the default time period. All items in +`` must be versioned items. + +If multiple `age-days` hints for a single package are available, +whichever is encountered first during parsing overrides the others. + +Provided by the `age` policy. + +### urgent `` + +Approximately equivalent to `age-days 0 `, with the +distinction that an "urgent" hint overrides any "age-days" hint for +the same action item. + +Provided by the `age` policy. + +### ignore-rc-bugs `` `` + +The `` argument is a comma separated list of bugs that +affect the items in ``. Britney will ignore these bugs +when determining whether the migration items have regressed compared +to the target suite. All items in `` must be versioned +items. + +Currently britney supports at most one active `ignore-rc-bugs` per +migration item. + +Provided by the `bugs` policy + +### ignore-piuparts `` + +The items in `` will not be blocked by regressions in +results from piuparts tests. All items in `` must be +versioned items. + +Provided by the `piuparts` policy + +### force `` + +Override all policies that claim the items in `` have +regressions or are otherwise not ready to migrate. All items in the +`` must be versioned items or architecture qualified +versioned items. + +This hint does not guarantee that they will migrate. To ensure that, +you will have to combine it with a `force-hint`. However, please read +the warning in the documentation for `force-hint` before you do this. + +## Migration selection hints + +All migration selection hints work on an "action list". This consists +of at least 1 or more of the following (in any combination): + + * Versioned item (e.g. `coreutils/8.27`) + * Architecture qualified versioned item (e.g. `coreutils/8.27-1/amd64`) + * The removal of either of the above (e.g. `-coreutils/8.27-1` or `-coreutils/8.27-1/amd64`) + +All elements in the action list must be valid at the time the hint is +attempted. Notably, if one action has already been completed, the +entire hint is rejected as invalid. + +### easy `` + +Perform all the migrations and removals denoted by `` as if +it was a single migration group. If the end result is equal or better +compared to the original situation, the action is committed. + +This hint is primarily useful if britney fails to compute a valid +solution for a concrete problem with a valid solution. Although, in +many cases, Britney will generally figure out the solution on her own. + +Note that for `easy` the `` must have at least two +elements. There is no use-case where a single element for easy will +make sense (as britney always tries those). + +### hint `` + +Perform all the migrations and removals denoted by `` as if +it was a single migration group. After that, process all remaining +(unmigrated) items and accept any that can now be processed. If the +end result is equal or better compared to the original situation, the +result is committed. Otherwise, all actions triggered by the hint are +rolled back. + +The primary difference between `easy` and `hint` is who carries the +burden of finding the solution. In an `easy` hint, the hinter must +provide a full valid and self-contained solution. Whereas with a +`hint`, the hinter can basically say "I want X to migrate, try to +figure out a solution for it". For the same reason, `hint`-hints are +rather expensive and should be used sparingly. + +This hint is primarily useful if britney fails to compute a valid +solution for a concrete problem with a valid solution. Although, in +many cases, Britney will generally figure out the solution on her own. + +*Caveat*: Due to "uninstallability trading", this hint may cause +undesireable changes to the target suite. In practise, this is rather +rare but the hinter is letting britney decide what "repairs" the +situation. + +### force-hint `` + +The provided `` is migrated as-is regardless of what is +broken by said migration. This often needs to be paired with a +`force`-hint to ensure that the actions are considered as valid +candidates. + +This hint is generally useful when the provided `` is more +desirable than the resulting breakage. + +*Caveat*: Be sure to test the outcome of these hints. A last minute +change can have long lasting undesireable consequences on the end +result. + +## Other hints + +This section cover hints that have no other grouping. + +### remove `` + +Britney should attempt to remove all items in the `` from +the target suite. The `` must consist entirely of +versioned items (note the items should *not* be prefixed with "-"). + +If an item in `` is not in the target suite that item is +silently ignored. + +Note: It is not possible to do architecture specific removals via +`remove`-hints.