1```{eval-rst} 2:orphan: 3``` 4 5# Communication templates related to release management 6 7## Deprecation notices 8 9Deprecation notices are part of release notes to act as a warning: at some 10point in the future some part of coreboot gets removed. That point must be 11at least 6 months after the release of the notice and it must be right after 12some release: That is, the specified release must still contain the part in 13question while one git commit later it might be removed. 14 15The usual reason is progress: Infrastructure module X has been replaced by 16infrastructure module X+1. Removing X helps keep the sources manageable 17and likely opens opportunities to improve the codebase even more. 18Sometimes everything using some module has been converted to its successor 19already and it's natural for such modules to be removed. Even then it might 20be useful to add an entry to the release notes to make everybody aware of 21such a change, for maintainers of incomplete boards that they might keep in 22their local trees and also to give credit to the developers of that change. 23 24However this template isn't about such cases. Sometimes the tree contains 25mainboards that rely on X and can't be easily migrated to X+1, often because 26no active developer has access to these mainboards, and that is where this 27type of deprecation notice comes in: 28 29A deprecation notice shall outline what is being removed, when it is planned 30for removal (always directly _after_ a future release so it remains clear when 31something is part of coreboot and when it isn't anymore) and which devices 32would be affected at the time of writing. Since past deprecation notices have 33been read as "we plan to remove mainboards A, B, and C", sparking outrage 34with the devoted users of A, B, or C, some care is necessary to make clear 35which parts are slated for removal and which parts are merely consequences 36if no action is taken. Or put differently: It should be obvious that besides 37the deprecation plan, there is a call to action to save a couple of devices 38from becoming officially unsupported. 39 40As such, consider the following template when announcing a deprecation: 41 42### The Thing to remove 43 44A short description of the Thing slated for removal. 45 46A short rationale why it's being removed (e.g. new and better Thing exists 47in parallel; new Thing already demonstrated to work in this many releases; 48removing Thing enables this or that improvement) 49 50Timeline: Announced here, Thing will be removed right after the release X 51months out (where X >= 6) 52 53#### Call to action 54 55Removing Thing requires work on a number of (boards, chipsets, …) that didn't 56make the switch yet. The work approximately looks like this: (e.g. pointers to 57commits where a board has been successfully migrated from Thing to new Thing). 58 59Working on migrating away from Thing involves (hardware components, coreboot 60systems, …) 1, 2, and 3. It's difficult to do on the remaining devices because 61... 62 63Parts of the tree that need work to become independent of Thing. 64 - chipset A 65 - board A1 66 - board A2 67 - chipset B 68 - board B1 69 70We prefer to move them along, but if we don't see any maintenance in our tree 71we'll have to assume that there's no more interest in these platforms. As a 72consequence these devices either have to work without Thing by the removal 73date or they will be removed together with Thing. (side note: these removals 74aren't the law, so if there's work in progress to move boards off X and a 75roadmap that makes it probable to succeed, just not within the announced 76deprecation timeline, we can still decide to postpone the actual removal by 77one release. This needn't be put in the release notes themselves though or 78it might encourage people to look for simple escape hatches.) 79 80(If there are developers offering to write patches: ) 81There are developers interested in helping move these forward but they can't 82test any changes for lack of equipment. If you have an affected device and 83can run tests on it, please reach out to developers α, β, and γ. 84 85(Otherwise maybe something more generic like this: ) 86If you want to take this on, the coreboot developer community will try to 87help you: Reach out through one of our [forums](../community/forums.md). 88