c52aecca11
While running Sphinx, it shows the warning "document isn't included in any toctree" for the documents checklist.md and templates.md. These are not meant to be listed in ToC trees. Thus, mark them as orphaned to exclude them from ToC trees. Change-Id: I1ff8f7c24ac9b3c3a120914c0c72ab73e85c4873 Signed-off-by: Felix Singer <felixsinger@posteo.net> Reviewed-on: https://review.coreboot.org/c/coreboot/+/62584 Reviewed-by: Thomas Heijligen <src@posteo.de> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
87 lines
4.1 KiB
Markdown
87 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).
|