More time between new things and deprecating old things

[jbscare]

If a new thing is introduced in version X, which will deprecate an old thing, it'd be nice to have a standard that the old thing isn't deprecated until version X+1, so that there's at least one version where both old and new things are supported without deprecation warnings.

[jbscare]

This came up in the context of check_mode, which is new in 2.2; but always_run is also deprecated in 2.2, so we can't update our playbooks to get rid of the always_run warnings if we're still running 2.1 anywhere. (We upgrade Ansible on our control hosts at around the same time, but not exactly the same time, so whoever isn't first is going to get annoying deprecation warnings immediately, and there's no way for them to avoid that.)

If always_run weren't deprecated until 2.3, we could upgrade without any annoying warnings.

[robinro]

always_run is still useable with 2.2. It only shows warnings, no errors and behaves as in 2.1.

The warnings exist to make sure users are aware of the upcoming deprecation in the future, that will remove support for that feature. Without a warning most users won't migrate if the old feature still works.

[jbscare]

Right, I understand the value of deprecation warnings, I'm just talking about the timing.

I'm suggesting, as a standard, that when a new thing is introduced in version X, which will deprecate an old thing, that the old thing not be deprecated until version X+1. That way, people can change their playbooks from the old way to the new way in Version X without getting any warnings. If they don't do that, they'll get warnings in version X+1; that's fine, they can at that point avoid warnings by changing their playbooks before they upgrade.

If a new thing is introdcued in version X, and the old thing is also deprecated in version X, there's no way to avoid getting warnings.

I feel like most of the time, it's worked the way I suggest -- when we started upgrading from 1.9 to 2.1, we got a bunch of deprecation warnings, and we were able to update our playbooks such that they still worked in 1.9, but also didn't get deprecation warnings in 2.1.

With always_run and check_mode, going from 2.1 to 2.2, we can't do that.

[robinro]

The difference between most 1.9/2.0 changes and always_run, check_mode:

old feature=always_run, new feature=check_mode, with X=2.1 and X+1=2.2, X+2=2.3

• X has old feature, does not have new feature
• X+1 has new feature, still supports old feature, warns when old feature is used
• X+2 has new feature, does not have old feature

old feature=bare variables, new feature="{{ var }}", with X=1.9 and X+1=2.0/2.1, X+2=2.2

• X has old feature, also supports new feature
• X+1 has new feature, still supports old feature, warns when old feature is used
• X+2 has new feature, does not have old feature

One could add an extra step, but to we really want to wait 3 major releases to make a new syntax standard? Warnings are really harmless and easy to filter.

[jbscare]

That makes sense, and I definitely like the "bare variables" way better.

I think there's some general tension between "warnings are harmless and easy to filter" and "warnings are designed to be annoying so that people will update their playbooks". Our experience is that the warnings are indeed annoying. (grin) And we don't want to ignore the warnings, because we do want to be warned if we fail to update our playbooks. We just want a point where we can update them without upgrading the software and without getting warnings.

I don't have a strong opinion about whether it would be problematic to wait three major releases before removing support for an old syntax (which is really what we're talking about -- the new syntax can be "standard" as soon as it's added, the only question is how fast the old syntax stops working), other than to say that I don't see a lot of harm in continuing to support an old syntax unless there's some reason not to. (If there's some reason to eliminate an old syntax early, it seems fine to me to make an exception, but I think that should be an exception rather than the norm.)

[jbscare]

One other question: What's our collective past experience with this like? How often have we historically done it the three-step way rather than the two-step way? You mentioned that "most 1.9/2.0 changes" were the three-step way; was that problematic? Were changes that were made in the two-step way smoother or easier or otherwise better?

[bcoca]

We already use 3 step, the current flow is is:

• X has old feature
• X+1 has old feature, also supports new feature, warns when old feature is used
• X+2 has new feature, still supports old feature, warns when old feature is used (default might flip)
• X+3 has new feature, does not have old feature

1.9/2.0 was different as there was a core rewrite, somethings we could not make follow the above flow. All things removed in 2.2 did follow this and were deprecated in 2.0, so you had 2.0 and 2.1 warning.

[jbscare]

In that flow, X+1 and X+2 are the same state. There's not a "X has old feature, also supports new feature" state where the old feature doesn't throw warnings.

[jbscare]

So to make this crystal clear, my proposed three-step is:

• X has old feature, does not have new feature
• X+1 has old feature, also supports new feature
• X+2 has new feature, still supports old feature, warns when old feature is used (default might flip)
• X+3 has new feature, does not have old feature

The only change there from #139 (comment) is that X+1 doesn't have warnings; only X+2 has warnings.

That gives a state where both features are supported, without warnings, so you can change your playbooks without upgrading the software, and then upgrade the software without changing your playbooks, and get no warnings at any point in that process.

[bcoca]

There is a difference, normally what the default behavior is (does not apply to all changes).

But giving no warning makes any other iteration normally useless. Bare variables, for example, have been on their way out since 1.6, but we still get people complaining in 2.2 (removed) even though warnings have been in 2.0 and above.

[abadger]

We talked this over and came to two conclusions:

• Having deprecated code without the code emitting a deprecation message isn't a good idea.
• We decided that it doesn't make sense for us to introduce a longer time period between deprecation and removal at this point.

So we're not going to change our releases and deprecation message strategy for this.

However, you can get this same effect at your site via the deprecation_warnings config option. You'll have to be vigilant about managing it, though, so that you don't miss deprecation warnings down the line:

• When you install a new ansible, set deprecation_warnings=False in ansible.cfg for boxes using that version.
• When you've upgraded previous ansible installations to the new version, set deprecation_warnings=True for boxes using that version.
• Proceed to fix the deprecations in your playbooks at this point.

It's important not to forget the second step otherwise you won't get the deprecations and be prompted to fix your playbooks. Sorry we aren't going to make a change to the deprecation policy but hopefully that will let you adapt your own workflow for this.