Documentation/releases/templates.md

   1 ```{eval-rst}
   2 :orphan:
   3 ```
   4
   5 # Communication templates related to release management
   6
   7 ## Deprecation notices
   8
   9 Deprecation notices are part of release notes to act as a warning: at some
  10 point in the future some part of coreboot gets removed. That point must be
  11 at least 6 months after the release of the notice and it must be right after
  12 some release: That is, the specified release must still contain the part in
  13 question while one git commit later it might be removed.
  14
  15 The usual reason is progress: Infrastructure module X has been replaced by
  16 infrastructure module X+1. Removing X helps keep the sources manageable
  17 and likely opens opportunities to improve the codebase even more.
  18 Sometimes everything using some module has been converted to its successor
  19 already and it's natural for such modules to be removed. Even then it might
  20 be useful to add an entry to the release notes to make everybody aware of
  21 such a change, for maintainers of incomplete boards that they might keep in
  22 their local trees and also to give credit to the developers of that change.
  23
  24 However this template isn't about such cases. Sometimes the tree contains
  25 mainboards that rely on X and can't be easily migrated to X+1, often because
  26 no active developer has access to these mainboards, and that is where this
  27 type of deprecation notice comes in:
  28
  29 A deprecation notice shall outline what is being removed, when it is planned
  30 for removal (always directly _after_ a future release so it remains clear when
  31 something is part of coreboot and when it isn't anymore) and which devices
  32 would be affected at the time of writing. Since past deprecation notices have
  33 been read as "we plan to remove mainboards A, B, and C", sparking outrage
  34 with the devoted users of A, B, or C, some care is necessary to make clear
  35 which parts are slated for removal and which parts are merely consequences
  36 if no action is taken. Or put differently: It should be obvious that besides
  37 the deprecation plan, there is a call to action to save a couple of devices
  38 from becoming officially unsupported.
  39
  40 As such, consider the following template when announcing a deprecation:
  41
  42 ### The Thing to remove
  43
  44 A short description of the Thing slated for removal.
  45
  46 A short rationale why it's being removed (e.g. new and better Thing exists
  47 in parallel; new Thing already demonstrated to work in this many releases;
  48 removing Thing enables this or that improvement)
  49
  50 Timeline: Announced here, Thing will be removed right after the release X
  51 months out (where X >= 6)
  52
  53 #### Call to action
  54
  55 Removing Thing requires work on a number of (boards, chipsets, …) that didn't
  56 make the switch yet. The work approximately looks like this: (e.g. pointers to
  57 commits where a board has been successfully migrated from Thing to new Thing).
  58
  59 Working on migrating away from Thing involves (hardware components, coreboot
  60 systems, …) 1, 2, and 3. It's difficult to do on the remaining devices because
  61 ...
  62
  63 Parts of the tree that need work to become independent of Thing.
  64  - chipset A
  65    - board A1
  66    - board A2
  67  - chipset B
  68    - board B1
  69
  70 We prefer to move them along, but if we don't see any maintenance in our tree
  71 we'll have to assume that there's no more interest in these platforms. As a
  72 consequence these devices either have to work without Thing by the removal
  73 date or they will be removed together with Thing. (side note: these removals
  74 aren't the law, so if there's work in progress to move boards off X and a
  75 roadmap that makes it probable to succeed, just not within the announced
  76 deprecation timeline, we can still decide to postpone the actual removal by
  77 one release. This needn't be put in the release notes themselves though or
  78 it might encourage people to look for simple escape hatches.)
  79
  80 (If there are developers offering to write patches: )
  81 There are developers interested in helping move these forward but they can't
  82 test any changes for lack of equipment. If you have an affected device and
  83 can run tests on it, please reach out to developers α, β, and γ.
  84
  85 (Otherwise maybe something more generic like this: )
  86 If you want to take this on, the coreboot developer community will try to
  87 help you: Reach out through one of our [forums](../community/forums.md).