Polkadot SDK is under constant development and improvement, thus deprecation and removal of existing code happen often. When creating a breaking change we need to be mindful that external builders could be impacted by this. The deprecation checklist 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 T15-deprecation needs to be created for correct tracking.
Then these are the actions to take:
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:
#[deprecated(note = "[DEPRECATED] will be removed after [DATE]. [ALTERNATIVE]")][ALTERNATIVE] won't always be possible but offer it if it is.
E.g.
#[deprecated(note = "`GenesisConfig` will be removed after December 2023. Use `RuntimeGenesisConfig` instead.")]Some pieces of code cannot be labeled as deprecated, like reexports or dispatchables, for instance. In cases like that we can only make a visible enough comment, and make sure that we announce the deprecation properly.
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.
Make sure that the rust docs are updated. We also need https://docs.substrate.io/ to be updated accordingly. The repo behind it is https://github.com/substrate-developer-hub/substrate-docs.
At minimum they should be noted in the release log. Please see how to document a PR here. There you can give instructions based on the audience and tell them what they need to do to upgrade the code.
Some breaking changes have a bigger impact than others. When the impact is big the release note is not enough, though it should still be the primary place for the notice. You can link back to the changelog files in other channels if you want to announce it somewhere else. Make sure you are as loud as you need to be for the magnitude of the breaking change.
Depending on the removal date indicated in the deprecation warning in the first step, the nature and the importance of the change, it might make sense to coordinate the release with other developers and with the Release team.
The deprecated code finally gets removed. Don’t forget to announce this accordingly.
✅ In order to not forget any of these steps, consider using this template in your deprecation issue:
### 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