Add more flexible 'deprecation' support.

[alikins]

Proposal: Add more flexible 'deprecation' support.

Author: Adrian Likins alikins@redhat.com Date: 2016-10-10

• Status: New
• Proposal type: core design
• Targeted Release: 2.3
• Associated PR: <link to GH PR in ansible/proposals if PR was submitted>
• Estimated time to implement: <X days, weeks, etc.>

  Motivation

During the preparation of major releases, the process of updating deprecations is a significant amount of work and can be trouble prone. Deprecations need to be found and documented, and code needs to be updated to remove deprecated code and warn/error on it's use.

Problems

What problems exist that this proposal will solve?

• Getting a release's deprecations ready is complicated and error prone.
• Information about pending deprecations is ad hoc and spread across the application and there is no mechanism to introspect it.
• Current deprecations are tied to the use of the 'display' module to evaluate deprecations, warn or error on their use, and to track what deprecation warnings have been issued. This functionality should not be closely coupled with the 'display' code.
• It is difficult to generate a list of 'things that were deprecated in 2.2'
• ansible deprecations are often tied to user facing features (ie, a playbook directive or config option). Most 'deprecation' tracking tools and approaches are focused on API deprecation and tied tightly to detecting use of specific modules/classes/methods/args.

  Solution proposal

• Add a 'deprecation' module that includes a Deprecation() class, and code to register, find, and evaluate Deprecation() objects
• Decouple checking of deprecations from displaying them (so deprecations could be display interactively, or via a logger, or via API)
• Centralize and organize the definition of deprecations.
• 'deprecation' module should support introspection of deprecations. This would allow for example, a cli option to show all feature deprecated in the current version or in a particular future version.
• 'deprecation' module would know what versions a feature is deprecated in, as well as knowing the current version. Revving the current version will automatically apply defined and registered deprecations.
• cli/config/env options to test against current/future deprecations. Some options:
  • --list-deprecations show all known deprecations and version info
  • --deprecations-from-future 2.4 would evaluate deprecations as if the current version is 2.4 (ie, so removal of features would error)
• Deprecation() objects would have a well known 'label' that can be used to reference them. This also allows deprecation warning tracking (ie, attempt to only show a warning once) to have a reliable identifier. (As opposed to something like 'warnings' module which largely matches on msg string comparison).
• Deprecation() classes would include docstrings that could be used for autogenerating documentation.
• prototype at https://github.com/alikins/ansible/tree/deprecation

In the future, could also support:

• cli options:
  • --list-seen-deprecations would display a list of deprecations seen why running a playbook (and when possible, including info about where they were encountered (this requires a fair amount of internal changes to track this info, so may need to be done later)
• if we add stdlib logging support, deprecation warnings could have their own logger (more or less equivalent to using the python 'warnings' module and 'logging.captureWarnings')

Example deprecation definitions:

class SudoUsage(Deprecation):
    label = SUDO_USAGE
    version = None
    removed = None
    message = "Instead of sudo/sudo_user, use become/become_user and set become_method to 'sudo' (default is sudo)")

class MergeMultipleCliSkipTags(Deprecation):
    label = MERGE_MULTIPLE_CLI_SKIP_TAGS
    version = 2.5
    removed = False
    message = 'Specifying --skip-tags multiple times on the command line currently uses the last specified value. In 2.4, values will be merged instead.  Set merge_multiple_cli_tags=True in ansible.cfg to get this behavior now.'

    def mitigated(self):
        '''If user has explicitly enable MERGE_MULTIPLE_CLI_TAGS, dont warn.'''
        return C.MERGE_MULTIPLE_CLI_TAGS

class ToBytes(Deprecation):
    label = TO_BYTES
    version = 2.4
    removed = None
    message = u'ansible.utils.unicode.to_bytes is deprecated.  Use ansible.module_utils._text.to_bytes instead'

API deprecation:

from ansible import deprecated

def to_bytes(*args, **kwargs):
    deprecated.check(deprecated.TO_BYTES)
     if 'errors' not in kwargs:
         kwargs['errors'] = 'replace'
     return _to_bytes(*args, **kwargs)

Feature deprecation:

from ansible import deprecated
<...>
def _preprocess_data_become(self, ds):
    <...>
    deprecated.check(deprecated.SUDO_USAGE)

Dependencies (optional)

Depends on final implementation, but there is no external deps required currently.

Testing (optional)

• would need to test that current, as well as future deprecations are find and handled correctly.

  Documentation (optional)

• needs developer documentation explain how to use the module
• if user facing features are added (for example, --list-deprecations or --from-future could be provided to show current deprecations, or to show what would warn/error with a future version) they need to be documented.

  Anything else?

Some similar tools (mostly focused on API deprecation)

• https://pypi.python.org/pypi/debtcollector
• https://pypi.python.org/pypi/zope.deprecation/4.1.2
• https://pypi.python.org/pypi/deprecator/0.3

[jctanner]

related https://github.com/ansible/ansible/pull/18470

[jctanner]

related https://github.com/ansible/ansible/issues/18559

[abadger]

-1. Adding registration is something that static language practitioners naturally reach for but isn't natural for dynamic languages. It gets in the way of both reading and writing code by forcing you to break out of the flow of the problem you are working on and into defining the type for an unrelated system. Reading through the reasons for this proposal, most of them can be solved without centralized registration. The only thing that is helped by registration is being able to list all of the deprecations in the code base. And that's justified for the purposes of building release notes, not an end user need (the end user needs to know what deprecations affect them, not all the potential deprecations exist). Listing all deprecations also doesn't work as it only registers code that has been reached at the time it has been called. Code that hasn't been reached at that point will not be included.

[bcoca]

-1 also, mostly I agree with @abadger there are much simpler solutions to deal with listing the deprecations for the changelog (i.e. grep) which, unlike the code, will deal with ALL of them, not just the ones in the branches of code hit.

[bcoca]

Closing as most of the problems stated have been addressed in alternative ways, we now have facilities to list deprecations and a process to handle removal on every new release cycle.