Better documentation around deprecation notices


#1

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