Deprecated functionality

[shadowspawn]

Pull Request

We keep functionality around to avoid breaking backwards compatibility for as long as reasonable.

How should we talk about old functionality, especially that we might delete one day? How do people find out about the new/better ways of doing things?

The semver pattern is to explicitly deprecate functionality before it can be removed in a future major version. We can do this early, or just-in-time with a minor release to deprecate some functionality and then remove it immediately in the next major version.

Problem

• how do we discourage use of old functionality?
• how do people with old code find out what it does?
• how to people with old code find out new approach?

Solution

Explicitly deprecate old functionality:

• remove from README (so new people don't see it)
• remove descriptions from JSDoc and TSDoc if does not break code
• mark as @deprecated if possible for IDE feedback
• add to separate documentation for deprecated routines
  • what it did
  • version it was deprecated
  • replacement
  • version it was deleted, if/when it is deleted

[shadowspawn]

(Previously started in #1314 but that included undocumented features, which was somewhat a contradiction. 😄 )

[abetomo]

It's very easy to understand.