88 lines
4.1 KiB
Markdown
88 lines
4.1 KiB
Markdown
```eval_rst
|
||
:orphan:
|
||
```
|
||
|
||
# Communication templates related to release management
|
||
|
||
## Deprecation notices
|
||
|
||
Deprecation notices are part of release notes to act as a warning: at some
|
||
point in the future some part of coreboot gets removed. That point must be
|
||
at least 6 months after the release of the notice and it must be right after
|
||
some release: That is, the specified release must still contain the part in
|
||
question while one git commit later it might be removed.
|
||
|
||
The usual reason is progress: Infrastructure module X has been replaced by
|
||
infrastructure module X+1. Removing X helps keep the sources manageable
|
||
and likely opens opportunities to improve the codebase even more.
|
||
Sometimes everything using some module has been converted to its successor
|
||
already and it's natural for such modules to be removed. Even then it might
|
||
be useful to add an entry to the release notes to make everybody aware of
|
||
such a change, for maintainers of incomplete boards that they might keep in
|
||
their local trees and also to give credit to the developers of that change.
|
||
|
||
However this template isn't about such cases. Sometimes the tree contains
|
||
mainboards that rely on X and can't be easily migrated to X+1, often because
|
||
no active developer has access to these mainboards, and that is where this
|
||
type of deprecation notice comes in:
|
||
|
||
A deprecation notice shall outline what is being removed, when it is planned
|
||
for removal (always directly _after_ a future release so it remains clear when
|
||
something is part of coreboot and when it isn't anymore) and which devices
|
||
would be affected at the time of writing. Since past deprecation notices have
|
||
been read as "we plan to remove mainboards A, B, and C", sparking outrage
|
||
with the devoted users of A, B, or C, some care is necessary to make clear
|
||
which parts are slated for removal and which parts are merely consequences
|
||
if no action is taken. Or put differently: It should be obvious that besides
|
||
the deprecation plan, there is a call to action to save a couple of devices
|
||
from becoming officially unsupported.
|
||
|
||
As such, consider the following template when announcing a deprecation:
|
||
|
||
### The Thing to remove
|
||
|
||
A short description of the Thing slated for removal.
|
||
|
||
A short rationale why it's being removed (e.g. new and better Thing exists
|
||
in parallel; new Thing already demonstrated to work in this many releases;
|
||
removing Thing enables this or that improvement)
|
||
|
||
Timeline: Announced here, Thing will be removed right after the release X
|
||
months out (where X >= 6)
|
||
|
||
#### Call to action
|
||
|
||
Removing Thing requires work on a number of (boards, chipsets, …) that didn't
|
||
make the switch yet. The work approximately looks like this: (e.g. pointers to
|
||
commits where a board has been successfully migrated from Thing to new Thing).
|
||
|
||
Working on migrating away from Thing involves (hardware components, coreboot
|
||
systems, …) 1, 2, and 3. It's difficult to do on the remaining devices because
|
||
...
|
||
|
||
Parts of the tree that need work to become independent of Thing.
|
||
- chipset A
|
||
- board A1
|
||
- board A2
|
||
- chipset B
|
||
- board B1
|
||
|
||
We prefer to move them along, but if we don't see any maintenance in our tree
|
||
we'll have to assume that there's no more interest in these platforms. As a
|
||
consequence these devices either have to work without Thing by the removal
|
||
date or they will be removed together with Thing. (side note: these removals
|
||
aren't the law, so if there's work in progress to move boards off X and a
|
||
roadmap that makes it probable to succeed, just not within the announced
|
||
deprecation timeline, we can still decide to postpone the actual removal by
|
||
one release. This needn't be put in the release notes themselves though or
|
||
it might encourage people to look for simple escape hatches.)
|
||
|
||
(If there are developers offering to write patches: )
|
||
There are developers interested in helping move these forward but they can't
|
||
test any changes for lack of equipment. If you have an affected device and
|
||
can run tests on it, please reach out to developers α, β, and γ.
|
||
|
||
(Otherwise maybe something more generic like this: )
|
||
If you want to take this on, the coreboot developer community will try to
|
||
help you: Reach out through one of our [forums](../community/forums.md).
|