Deprecation Guidelines#

Deprecation is an important part of the development life-cycle and a signal for users to help with migrations. Deprecations can occur either during a major release, or between major releases. The deprecation process is really part of a larger migration documentation process, and it provides a good last line of defense for users on how to migrate their code.

Note

See Versioning section for more details on release types.

Major Release Deprecations#

These are deprecations that occur during a major release. Generally these are deprecations necessary for the release to work, and must be at versions: Major.0.0. For these deprecations the guidelines are:

  1. Try not to break too much.

  2. Warn with a DeprecationWarning if the deprecated function is still usable. Otherwise raise it as an Exception.

  3. Add clear documentation on the fact it is deprecated and what the alternative is.

  4. Write a migration plan, preferably it should be part of the releases prior the major release.

  5. Only clear these DeprecationWarnings at the next major release.

Mid-Major Release Deprecations#

These are deprecations that are not during a major release. That is when the version matches: Major.Minor.0 or Major.Minor.Patch. The guidelines are:

  1. Do not break anything

  2. Warn with a DeprecationWarning (or PendingDeprecationWarning, or FutureWarning as appropriate. See the guide on warnings.)

  3. Add clear documentation on the fact it is deprecated and what the alternative is.

  4. Clear these warnings and documentation notations at the next major release.