Patrick Georgi has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/59677 )
Change subject: Documentation: Add template for deprecation notices ......................................................................
Documentation: Add template for deprecation notices
Change-Id: Ia2cc4f799804c7d56db572823246c487cd19a726 Signed-off-by: Patrick Georgi patrick@coreboot.org --- M Documentation/releases/index.md A Documentation/releases/templates.md 2 files changed, 75 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/77/59677/1
diff --git a/Documentation/releases/index.md b/Documentation/releases/index.md index 16d2fef..90e8e40 100644 --- a/Documentation/releases/index.md +++ b/Documentation/releases/index.md @@ -23,6 +23,11 @@
* [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 0000000..cdcd169 --- /dev/null +++ b/Documentation/releases/templates.md @@ -0,0 +1,70 @@ +# Communication templates related to release management + +## Deprecation notices + +Deprecation notices are part of release notes to act as a warning that a +certain number of releases down the road (must cover at least 6 months from +the release that comes with the notice) some part of coreboot gets 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 improving the codebase even more. Modules +that fell entirely out of use because everything has been removed and which +provide no external interface unique to them can be removed silently. + +There are cases where 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. This is where the deprecation notice comes in: + +A deprecation notice shall line out what is being removed, when it is planned +for removal (always directly _after_ a future release to 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. + +Parts of the tree that need work to become independent of Thing. + - board A + - board B + - board C + - chipset D + +We prefer to move them along, but if we don't see any maintenance in our +tree we can't expect them to work, no matter if we leave Thing in or not. The +consequence is that either they will work without Thing by the removal date +or they will be removed together with Thing. + +(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 on the mailing list, IRC, ... (link to forums page?)
-
Patrick Georgi (Code Review)