84 lines
4.1 KiB
Markdown
84 lines
4.1 KiB
Markdown
|
# 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).
|