I have a question on breaking changes and their documentation in the changelog. As a reminder, creating a changelog fragment states that breaking changes
MUST include changes that break existing playbooks or roles. This includes any change to existing behavior that forces users to update tasks. Breaking changes means the user MUST make a change when they update. Breaking changes MUST only happen in a major release of the collection.
I’ve stumbled on this because community.mysql 4.2.0 had a breaking change making it incompatible with Python 2. However, there has already been a breaking change in 4.0.0 dropping support for Python 2.
I’ve been confused to see a breaking change in a minor release. On the other hand, support for Python 2 has already been dropped in 4.0.0. I wonder how we should document this.
Breaking change in 4.0.0 to drop Python 2 (or ansible-core X or whatever Y) support even if there haven’t been any changes to code that makes it really incompatible with this plus another breaking change when this really happens? (I don’t like this, breaking changes in minor releases always make me uncomfortable.)
Don’t do a new major release to drop support for whatever when there are no changes to the code that make it really incompatible; do a major release announcing breaking changes when there are really changes to the code that introduce incompatibilities?
Announce dropping support for whatever as a breaking change in a new major release even the the collection still works with it, and then announce the actual introduction of incompatibilities as something else (major changes or removed features)?
Something else?
I tend to 3 but I think this is worth a discussion. Especially since my preference is somewhat incompatible with “breaking changes means the user MUST make a change when they update”. I mean, dropping support for X while the collection still works with it means the user does not have to make a change when they update.
Apropos of nothing, am I the only one who finds it somewhat weird that major changes don’t require a major release? From the description, it makes sense because major changes are not breaking. But it’s still… well, confusing.
I think the change in version 4.2.0 is simply a bugfix or minor change, since it’s basically a refactoring that shouldn’t have any effect on users that use a supported ansible-core / Python version.
This is how I’ve been handling such changes before, and also have seen it in other projects and collections.
Just because “major release” and “major change” use the same word “major” doesn’t mean they are releated
In my head, “drop support for ___” means “we no longer test against ___.” If there’s a breaking change and I’m still running ___, then that’s on me.
Sometimes changes are known to be incompatible with ___, in which case a changelog entry to that effect is welcome, but I as a user can’t expect everything that may “work differently to the point of being unusable in my environment” to be documented as such by core or module / role / collection developers.
At best, such rules are aspirational. Stuff will slip through. It’s good to think about these things and try to be helpful with changes, but in the end we’re dancing on pin-heads (an English expression for - in this case - arguing for various positions which in the end have no salient distinctions from a user’s perspective).
Sounds reasonable. This is also how I do it in community.vmware. But then we should possibly drop “breaking changes means the user MUST make a change when they update”. In my example (community.mysql 4.0.0) users probably didn’t have to make a change. The collection was still working with Python 2, at least as far as I understand. So:
MUST include changes that break existing playbooks or roles. This includes any change to existing behavior that forces users to update tasks. Breaking changes MUST only happen in a major release of the collection.
Or do you think we should explicitly mention dropping support for something there?
I guess the problem with “the user MUST make a change” is that it’s not clear which user is meant. Users that don’t use something aren’t affected by a breaking change. Maybe say “a user of some of the aspects that are changing MUST make a change” would be better?
Dropping support for say Python 2 means that a user that uses some of the modules on a Python 2 target must change something (like make sure that a Python 3 interpreter is there on the target, and Ansible will use that one for executing modules).
