diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/releases/index.md | 5 | ||||
| -rw-r--r-- | Documentation/releases/templates.md | 83 |
2 files changed, 88 insertions, 0 deletions
diff --git a/Documentation/releases/index.md b/Documentation/releases/index.md index 16d2fef919..90e8e40942 100644 --- a/Documentation/releases/index.md +++ b/Documentation/releases/index.md @@ -23,6 +23,11 @@ names etc. * [checklist](checklist.md) +For release related communications consider using a template so everything +important is taken care of. + +* [templates](templates.md) + Upcoming release ---------------- diff --git a/Documentation/releases/templates.md b/Documentation/releases/templates.md new file mode 100644 index 0000000000..86973eb7a3 --- /dev/null +++ b/Documentation/releases/templates.md @@ -0,0 +1,83 @@ +# 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). |