Add deprecation checklist document for Substrate

substrate/docs/deprecation-process.md

@@ -0,0 +1,76 @@
+# Deprecation Process
+
+This deprecation process makes sense while we don’t use [SemVer](https://semver.org/).
+After that, this process will most likely change.
+As deprecation and removal of existing code can happen on any release, we need to be mindful that external builders
+could be impacted by the changes we make.
+The deprecation process tries to mitigate this impact, while still keeping the developer experience, the DevEx, as
+smooth as possible.
+
+To start a deprecation process a new issue with the label `I11-deprecation` needs to be created for correct tracking.
+Then these are the actions to take:
+
+## Hard deprecate by adding a warning message
+
+The warning message shall include a removal month and year, which is suggested to be 6 months after the deprecation
+notice is released.
+This means that the code will be removed in a release within that month (or after, but never before). Please use this
+template, doing so makes it easy to search through the code base:
+
+```rust
+#[deprecated(note = "[DEPRECATED] will be removed after [DATE]. [ALTERNATIVE]")]
+```
+`[ALTERNATIVE]` won't always be possible but offer it if it is.
+
+E.g.
+```rust
+#[deprecated(note = "`GenesisConfig` will be removed after December 2023. Use `RuntimeGenesisConfig` instead.")]
+```
+
+Some pieces of code cannot be labeled as deprecated, like [reexports](https://github.com/rust-lang/rust/issues/30827)
+or [dispatchables](https://github.com/paritytech/polkadot-sdk/issues/182#issuecomment-1691684159), for instance.
+In cases like that we can only make a visible enough comment, and make sure that we [announce the deprecation properly](#announce-the-deprecation-and-removal).
+
+## Remove usage of the deprecated code in the code base
+
+Just make sure that we are not using the deprecated code ourselves.
+If you added the deprecation warning from the previous step, this can be done by making sure that warning is not shown
+when building the code.
+
+## Update examples and tutorials
+
+Make sure that the rust docs are updated.
+We also need [https://docs.substrate.io/](https://docs.substrate.io/) to be updated accordingly. The repo behind it is
+[https://github.com/substrate-developer-hub/substrate-docs](https://github.com/substrate-developer-hub/substrate-docs).
+
+## Announce the deprecation and removal
+
+**At minimum they should be noted in the release log.** Please see how to document a PR [here](https://github.com/paritytech/polkadot-sdk/blob/master/docs/CONTRIBUTING.md#documentation).
+Sometimes the release note is not enough.
+Make sure you are as loud as you need to be for the magnitude of the breaking change. Some breaking changes have a
+bigger impact than others.
+
+## Removal version is planned
+
+Depending on the removal date indicated in the deprecation warning in the [first step](#hard-deprecate-by-adding-a-warning-message),
+the nature and the importance of the change, it might make sense to coordinate the release with other developers and
+with the Release team.
+
+## Deprecated code is removed
+
+The deprecated code finally gets removed.
+Don’t forget to [announce this accordingly](#announce-the-deprecation-and-removal).
+
+✅ In order to not forget any of these steps, consider using this template in your deprecation issue:
+
+```markdown
+### Tasks
+
+- [ ] Deprecate code by adding a warning message
+- [ ] Remove usage of the deprecated code in the code base
+- [ ] Update examples and tutorials
+- [ ] Announce code deprecation
+- [ ] Plan removal version
+- [ ] Announce code removal
+- [ ] Remove deprecated code
+```