Avoid deprecating old when new was just introduced

[dagwieers]

Proposal: Delay deprecation for one release

Author: Dag Wieers <@dagwieers>

Date: 2017/10/31

• Status: New
• Proposal type: process
• Targeted Release: 2.4
• Associated PR: <link to GH PR in ansible/proposals if PR was submitted>
• Estimated time to implement: Immediate

Motivation

Today when we rewrite a core part of Ansible that influences how users write playbooks (e.g. the new loop implementation), we introduce this in a new version (devel and future v2.5) and immediately add deprecation warnings for the old syntax/functionality.

This practice is very inconvenient for organisations that test their code on both stable and devel branches, and while they could disable deprecation warnings, that's not a structural solution.

If they would rewrite their code to use the new functionality, they can't run it on stable, if they don't, they have to disable all deprecation warnings. In the past (can't remember which release/functionality) we had issues where the new functionality had some problems during the first release (use-cases not being covered) but were told the old functionality was deprecated; and so stable users had the same situation.

I would propose to delay the deprecation of old functionality with one release, and reduce the deprecation period with one release. So the total time-to-deprecation stays exactly the same, but we just get one stable release where both old and new functionality are available without any nagging.

Problems

What problems exist that this proposal will solve?

• A way to introduce and test new functionality without nagging users with deprecation messages
• A way to avoid deprecation messages in production/development environments (remember that in larger organisations the people automating are not necessarily the same people that run this on a day-to-day basis)

Solution proposal

• Introduce some new functionality in the next release
• Delay deprecation warnings for one stable release
• Just like we now have a due-release version added to a deprecation warning, we could add a start-release version so that the deprecation warning is being suppressed even when that infrastructure has been added.

[bcoca]

We already introduce features with 'delayed' deprecation, I would point at include_role/import_role and become as examples. If you want to propose changing the deprecation period for with_, that is a discussion we can have on that particular feature.

As for getting deprecation when looking at 2 versions, that would happen even when we deffer them, It just postpones the issue for 1 version.

[dagwieers]

@bcoca I didn't know/realize this was done before. But for major user-facing changes I would prefer if we made this the default.

And yes, it happens when you defer, but at that time one can migrate her playbooks and still run them in the previous/latest stable release. So not caught up in a bind.

[abadger]

If we simultaneously reduce the deprecation period I might be okay with this.

[gundalow]

Given we now have +4 deprecation cycle is this still needed?

[dagwieers]

What do you mean with +4 deprecation cycle ?

My main point is dat we should not deprecate old functionality at the same time that we introduce the replacement functionality. We should be able to have at least one release where the old and the new work together without any deprecation messages so companies can have playbooks that work on both an older and newer release without having to choose.

[dagwieers]

BTW We now did this for the new loop-syntax in v2.5, the deprecation messages were postponed so people can start enabling it in devel branch and be sure it also works on stable.

[bcoca]

that was always my intention, i only deprecated it initially so devel users would test loop well :smiling_imp: