Documentation: Add template for deprecation notices
Change-Id: Ia2cc4f799804c7d56db572823246c487cd19a726
Signed-off-by: Patrick Georgi <patrick@coreboot.org>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/59677
Reviewed-by: Felix Singer <felixsinger@posteo.net>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
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..86973eb
--- /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).