It seems like a lot of value could be added if we started adding references and identifiers on the deprecation notices.
I would propose it take the following form:
- Deprecation message
- Link or reference to deprecation “tech note” number
Tech Note would be published either on the website or in a github repository wiki page
The tech note should address the following:
- General reason for deprecation (bug fix, feature change, API improvement, performance tweak, etc)
- Affected code and common use cases/code examples before and after.
- Reference to affected source code
- Optionally: some upgrade path or future best practices.
- Optionally: estimation of when the feature will be removed.
- Optionally: ability for community to provided feedback and commentary
- Optionally: a voting or survey system to understand how many people the change affects.
A little bit of discipline around this would go a long way in helping people, understand, adjust, cope with and manage change to the framework over time. Such a good job is done commenting and documenting the source code with deprecation notices, it seems a no brainer to add this kind cross reference footnotes.
It doesn’t even have to be a hyperlink just a hint on where to get the full details of the change and why.
DEPRECATION: Some message goes here. For more info see technote #123