Devuan deployment of britney2
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 

345 lines
13 KiB

  1. .. _hints:
  2. Hints
  3. =====
  4. This document describes the `britney hints` and the format of the hint
  5. file. All hints are basically small instructions to britney. The
  6. vast majority of them involve overriding a quality gating policy in
  7. britney. However, there are a few hints that assist britney into
  8. finding solutions that it cannot compute itself.
  9. There are the following type of hints:
  10. * Policy overrides
  11. * Migration selections (with or without overrides)
  12. * Other
  13. Please see :doc:`setting-up-britney` for how to configure hint files
  14. and for how to limit which hints are allowed in a given hint file.
  15. Format of the hint file
  16. -----------------------
  17. All hints are read from hint files. The hint file is a plain text file
  18. with line-based content. Empty and whitespace-only lines are ignored.
  19. If the first (non-whitespace) character is a `#`, then britney
  20. considers it a comment and ignores it. However, other tooling may
  21. interpret these comments (as is the case for e.g. some parts of the
  22. Debian infrastructure).
  23. The remaining lines are considered space-separated lists, where the
  24. first element must be a known hint. The remaining elements will be
  25. interpreted as its arguments. Britney generally warns on and then
  26. discards unknown hints or hints with invalid arguments.
  27. The following are common types of arguments for hints:
  28. * Unversioned item, format: `<item name>`
  29. * Versioned item, format: `<item name>/<version>`
  30. * Architecture-qualified versioned item: `<item name>/<version>/<architecture>`
  31. (The above-mentioned types correspond to britney migration item types)
  32. Generally, for hints, all item names will be names of source packages.
  33. Furthermore, some hints also accept a `-` before the item name. This
  34. generally refers to the removal of said item rather than the migration
  35. of the hint.
  36. Policy override hints
  37. ---------------------
  38. The policy override hints are used to disable or tweak various
  39. policies in britney. Their effects are generally very precise ways of
  40. accepting specific regressions or disabling various checks.
  41. Some of these items are built-in while others are related to specific
  42. policies. In the latter case, they are only valid if the given policy
  43. is enabled (as the policy registers them when it is enabled).
  44. block-all `<type>`
  45. ^^^^^^^^^^^^^^^^^^
  46. Usually used during freezes to prevent migrations by default.
  47. The `<type>` can be one of:
  48. * `source`: Blocks all source migrations. This is a superset of
  49. `new-source`.
  50. * `new-source`: Block source migrations if the given source is not
  51. already in the target suite. (Side-effect: Removed packages will
  52. not re-enter the taget suite automatically).
  53. All variants of these can be overruled by a valid `unblock`-hint.
  54. Note that this does not and cannot restrict architecture specific
  55. migrations (e.g. binNMUs or first time builds for architectures).
  56. block `<action list>`, block-udeb `<action list>`
  57. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  58. Prevent the items in the `<action list>` from migrating until the hint
  59. is removed or overruled by the equivalent unblock hint (or a
  60. `remove`-hint). All items in the `<action list>` must be unversioned
  61. items and can be prefixed with `-` to prevent removal by built-in
  62. policies. However, it will not prevent removals requested by a
  63. `removal`-hint.
  64. The `block-udeb` is mainly intended for preventing accidental
  65. migration of installer-related packages during the later stages of the
  66. release cycle.
  67. Note that this does not and cannot restrict architecture specific
  68. migrations (e.g. binNMUs or first time builds for architectures).
  69. unblock `<action list>`, unblock-udeb `<action list>`
  70. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  71. Enable the items in `<action list>` to migrate by overriding `block`-,
  72. `block-all`- or `block-udeb`-hints. The `unblock`-hint (often under
  73. its synonym `approve`) is also used to approve migrations from source
  74. suites that require approval.
  75. The items in `<action list>` must all be versioned items.
  76. The `unblock-udeb` is mainly intended for preventing accidental
  77. migration of installer-related packages during the later stages of the
  78. release cycle.
  79. The two types of block hint must be paired with their corresponding
  80. unblock hint - i.e. an `unblock-udeb` does not override a `block`.
  81. approve `<action list>`
  82. ^^^^^^^^^^^^^^^^^^^^^^^
  83. A synonym of `unblock`. The variant is generally used for approving
  84. migrations from suites that require approvals.
  85. Aside from the tab-completion in the hint testing interface, which
  86. will give different suggestions to `approve` and `unblock`, the rest
  87. of britney will consider them identical.
  88. age-days `<days>` `<action list>`
  89. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  90. Set the length of time which the listed action items must have been in
  91. unstable before they can be considered candidates. This may be used
  92. to either lengthen or reduce the default time period. All items in
  93. `<action list>` must be versioned items.
  94. If multiple `age-days` hints for a single package are available,
  95. whichever is encountered first during parsing overrides the others.
  96. Provided by the `age` policy.
  97. urgent `<action list>`
  98. ^^^^^^^^^^^^^^^^^^^^^^
  99. Approximately equivalent to `age-days 0 <action list>`, with the
  100. distinction that an "urgent" hint overrides any "age-days" hint for
  101. the same action item.
  102. Provided by the `age` policy.
  103. ignore-rc-bugs `<bugs>` `<action list>`
  104. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  105. The `<bugs>` argument is a comma separated list <bugs> of bugs that
  106. affect the items in `<action list>`. Britney will ignore these bugs
  107. when determining whether the migration items have regressed compared
  108. to the target suite. All items in `<action list>` must be versioned
  109. items.
  110. Currently britney supports at most one active `ignore-rc-bugs` per
  111. migration item.
  112. Provided by the `bugs` policy
  113. ignore-piuparts `<action list>`
  114. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  115. The items in `<action list>` will not be blocked by regressions in
  116. results from piuparts tests. All items in `<action list>` must be
  117. versioned items.
  118. Provided by the `piuparts` policy
  119. force `<action list>`
  120. ^^^^^^^^^^^^^^^^^^^^^
  121. Override all policies that claim the items in `<action list>` have
  122. regressions or are otherwise not ready to migrate. All items in the
  123. `<action list>` must be versioned items or architecture qualified
  124. versioned items.
  125. This hint does not guarantee that they will migrate. To ensure that,
  126. you will have to combine it with a `force-hint`. However, please read
  127. the warning in the documentation for `force-hint` before you do this.
  128. force-badtest `<action list>`
  129. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  130. Ignore the autopkgtest regressions for the items in `<action list>`. This hint
  131. acts on the tests that are part of the source package of those items (in
  132. contrast to `force-skiptest`). It basically marks a particular test as not
  133. useful for the autopkgtest policy, e.g. because they are flaky. All items in
  134. the `<action list>` must be versioned items (potentially versioned 'all').
  135. The effect of this hint is not limited to the items listed in `<action list>`:
  136. this hint influences how autopkgtest regressions are treated for all the
  137. dependencies of the items in `<action list>`. The hint only influences the
  138. treatment of the tests that are part of the source packages listed in `<action
  139. list>`. If the dependencies trigger regressions in autopkgtests that are part
  140. of source packages not listed in `<action list>`, this hint will not affect
  141. those, so they can still cause items not to migrate.
  142. This hint does not guarantee that any item will migrate, it merely influences
  143. how an autopkgtest regression is treated. Migration can still be blocked or
  144. delayed for other reasons (like age, dependencies, piuparts regressions, etc).
  145. force-skiptest `<action list>`
  146. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  147. Ignore the autopkgtest regressions for the items in `<action list>`. This hint
  148. acts on all the tests that are triggered to test the items in the `<action
  149. list>`, but only when evaluting those items (in contrast to `force-badtest`).
  150. It disables autopkgtest policy from blocking items from the `<action list>`.
  151. All items in the `<action list>` must be versioned items.
  152. The effect of this hint is limited to the items listed in `<action list>`. Any
  153. autopkgtest result that would otherwise affect the migration of these items,
  154. will be ignored for these items only. These tests can still affect the
  155. migration of other items.
  156. This hint guarantees that the listed items will not be blocked or delayed by
  157. autopkgtest regression, but it does not guarantee that any item will migrate.
  158. Migration can still be blocked or delayed for other reasons (like age,
  159. dependencies, piuparts regressions, etc).
  160. allow-archall-maintainer-upload `<action list>`
  161. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  162. Allow the arch: all binaries of the sources specified in `<action list>` to be
  163. maintainer uploads.
  164. The items in `<action list>` are unversioned source package names.
  165. Migration selection hints
  166. -------------------------
  167. All migration selection hints work on an "action list". This consists
  168. of at least 1 or more of the following (in any combination):
  169. * Versioned item (e.g. `coreutils/8.27`)
  170. * Architecture qualified versioned item (e.g. `coreutils/8.27-1/amd64`)
  171. * The removal of either of the above (e.g. `-coreutils/8.27-1` or `-coreutils/8.27-1/amd64`)
  172. All elements in the action list must be valid at the time the hint is
  173. attempted. Notably, if one action has already been completed, the
  174. entire hint is rejected as invalid.
  175. easy `<action list>`
  176. ^^^^^^^^^^^^^^^^^^^^
  177. Perform all the migrations and removals denoted by `<action list>` as if
  178. it were a single migration group. If the end result is equal or better
  179. compared to the original situation, the action is committed.
  180. This hint is primarily useful if britney fails to compute a valid
  181. solution for a concrete problem with a valid solution. Although, in
  182. many cases, britney will generally figure out the solution on its own.
  183. Note that for `easy` the `<action list>` must have at least two
  184. elements. There is no use-case where a single element for easy will
  185. make sense (as britney always tries those).
  186. hint `<action list>`
  187. ^^^^^^^^^^^^^^^^^^^^
  188. Perform all the migrations and removals denoted by `<action list>` as if
  189. it were a single migration group. After that, process all remaining
  190. (unmigrated) items and accept any that can now be processed. If the
  191. end result is equal or better compared to the original situation, the
  192. result is committed. Otherwise, all actions triggered by the hint are
  193. rolled back.
  194. The primary difference between `easy` and `hint` is who carries the
  195. burden of finding the solution. In an `easy` hint, the hinter must
  196. provide a full valid and self-contained solution. Whereas with a
  197. `hint`, the hinter can basically say "I want X to migrate, try to
  198. figure out a solution for it". For the same reason, `hint`-hints are
  199. rather expensive and should be used sparingly.
  200. This hint is primarily useful if britney fails to compute a valid
  201. solution for a concrete problem with a valid solution. Although, in
  202. many cases, britney will generally figure out the solution on its own.
  203. *Caveat*: Due to "uninstallability trading", this hint may cause
  204. undesirable changes to the target suite. In practise, this is rather
  205. rare but the hinter is letting britney decide what "repairs" the
  206. situation.
  207. force-hint `<action list>`
  208. ^^^^^^^^^^^^^^^^^^^^^^^^^^
  209. The provided `<action list>` is migrated as-is regardless of what is
  210. broken by said migration. This often needs to be paired with a
  211. `force`-hint to ensure that the actions are considered as valid
  212. candidates.
  213. This hint is generally useful when the provided `<action list>` is more
  214. desirable than the resulting breakage.
  215. *Caveat*: Be sure to test the outcome of these hints. A last minute
  216. change can have long lasting undesirable consequences on the end
  217. result. Consider using an `allow-uninst` hint instead.
  218. Other hints
  219. -----------
  220. This section cover hints that have no other grouping.
  221. allow-uninst `<action list>`
  222. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  223. When trying migration of items, don't consider the uninstallability of binary
  224. packages in the `<action list>`. This means that items can still migrate if
  225. they cause these packages to become uninstallable.
  226. The `<action list>` is a list of unversioned binary packages. If an
  227. architecture is specified, it only applies to the specific architecture.
  228. Please note that the specified architecture is the architecture where Britney
  229. does the installability test. For arch: all package, this means that all
  230. relevant (`nobreakall`) architectures need to be specified, not `all`.
  231. remove `<action list>`
  232. ^^^^^^^^^^^^^^^^^^^^^^
  233. Britney should attempt to remove all items in the `<action list>` from
  234. the target suite. The `<action list>` must consist entirely of
  235. versioned items (note the items should *not* be prefixed with "-").
  236. If an item in `<action list>` is not in the target suite that item is
  237. silently ignored.
  238. Note: It is not possible to do architecture specific removals via
  239. `remove`-hints.