CfgMgmtCamp 2026 discussion (3/12): Big breaking changes come with no explanation of why they are happening

Project Discussions
, , ,
1

As a user

Big breaking changes come with no explanation of why they are happening

Latest developments

This was discussed at CfgMgmtCamp 2026.

For this specific deprecation, security considerations were the main motivation for the deprecation: modules executed on the target can return arbitrary facts, which can shadow arbitrary variables; depending on the roles/playbooks run, this could result in arbitrary code execution on the controller.

It was general consensus that communications for deprecations should be improved, both for ansible-core and for collections. The decision (with reasoning!) for deprecation should be documented somewhere and hopefully be linked to in the deprecation warning. (According to @nitzmahone some warnings / deprecation messages in the past had URLs to more detailled explanation, like the change to Python interpreter discovery.)

There have been various suggestions on how to handle this:

  • Simply use issues or files in the repository that summarize the decision and reasoning and link to relevant discussions and PRs.
  • Store Architectural Decision Records as files in the repository which contain detailed information on this.
  • Have a subdomain (kind of a link shortener) for redirecting to the latest version of such a discussion (in case it is moved).
  • How much should this be standardized? And how complex / complicated should this end up to be? If it’s too complex / too much a hassle, collection developers/maintainers might not use it.

Original text

Sometimes suddenly things are deprecated without an explanation of why. This is especially annoying and important for things that have been in place for a long time.

One specific instance here is deprecating the current default of INJECT_FACTS_AS_VARS, which right now causes a deprecation message with ansible-core 2.20 every time you use a fact like ansible_distribution without accessing it through ansible_facts (which would be ansible_facts.distribution or ansible_facts["distribution"]). Porting guide and changelog mention no rationale for this deprecation. It took a question on the forum to eventually (after 1.5 months) get some hints to why this was deprecated (“‘injection’ creates many issues for a very small convenience”, “injection uses a lot more memory and cpu time, aside from creating possible collisions and security issues”).

It would be great if communication in case of deprecations and breaking changes could be improved.

(And yes, this likely also applies to many other deprecations in collections - I likely also announced something as deprecated that should have come with a better explanation of why. There should always be links pointing back to issues and PRs, but figuring out why something was deprecated by dwelling into a system of links and reading through long discussions really isn’t user-friendly.)

2 Likes
CfgMgmtCamp 2026 discussion (0/12): Problems in the Ansible world and how to improve on them
CfgMgmtCamp 2026: Community and Contributor Summit
The Bullhorn #218
2

I don’t see us implementing formal processes like ADRs or standardized deprecation documentation - that doesn’t align with how the core team operates.

Deprecation decisions are made by the core team based on technical merit. The reasoning exists in PR/issue discussions for those who want to dig into specifics. We can try to be clearer in deprecation warnings themselves when it’s straightforward, but I’m not planning to commit to a formal justification process beyond what’s already captured in our standard development workflow at this time.

3

In the above example, it does not.

First, there is no porting guide entry (edit: there is one, but it doesn’t explain why it is deprecated, or provide links, and the PR adding it doesn’t have infos either), and the changelog simply states that it is deprecated, without any reason. It does not even contain a link to an issue or PR.

(This is something that ansible-core’s changelog is quite bad at. The changelog section of the development process for ansible-core explicitly states Each changelog entry must contain a link to its issue between parentheses at the end. If there is no corresponding issue, the entry must contain a link to the PR itself. If you scroll through the ansible-core 2.20 changelog, as an example, you can see that less of all entries have a link.)

Then if you dig out the PR (you can’t find it when searching for INJECT_FACTS_AS_VARS, so it’s not that easy either) (here is the PR), you can see that it does not refer to an issue, and doesn’t contain any more information on why this deprecation is happening either.

Also when searching the issues, there doesn’t seem to be a corresponding issue.

So in this case, if the information was available somehwere, it’s pretty hard to find.

3 Likes
4

One thing that I would really like to see is a small overview page showing the current deprecations (including in which version the thing will be removed) and which versions is needed to use the new behaviour.

I am not sure since when the ansible_facts functionality is present, to use Felix’ example. And to properly rewrite playbooks/collections/roles it would be great to note which version is needed to make this work (other than just say “use latest”, which is not always possible).

Kind Regards,
Johannes

2 Likes
5

Hmmm, I like parts of this a lot- the way we currently manually document deprecations only in the changelog for the version it first appears in makes this horrible for users to assemble, but would also be an absolute nightmare for us to maintain manually…

Referencing our push to make long-running non-atomic code tasks declarative/SSOT over on 8/12, and thinking about the granular warning control stuff we’ve been kicking around, this seems like something we should be able to generate pretty easily directly from the code as part of that work using the same extraction mechanisms that the deprecation sanity tests use. I’d be happy to trade more detailed inline declarative descriptions of deprecations for manually crafted changelog/porting guide entries on those things- especially if we could tie it in with the “externally linked documentation in error/deprecation/warning” stuff.

I’m less sure about how workable the second half of that ask might be to generate, but might be doable in, e.g., the non-versioned community docs build, pulling from the same declarative metadata we’d cough up for the “all pending deprecations in this release”.

2 Likes
6

@kastl-ars As @nitzmahone says, this sounds really interesting. A lot of the deprecation data we have in the changelogs and modules is structured data, so we could display that in different styles. It’s been some time since I’ve looked at how Ansible Doc does deprecations and if we have structured meta data there.

I’d be interested in what you (and others) think these new pages could look like.

1 Like
7

I think the page could start pretty basic. Starting with the chronologically “next” deprecations, sorted by Ansible release they will be deprecated in.

## Deprecations in Ansible 2.21

- Deprecate using something, please use something else as replacement
  Replacement introduced in: Ansible 2.19

## Deprecations in Ansible 2.24
- Deprecate this and that
  Replacement introduced in: Ansible 2.20

Having links to the releas notes or porting guide would of course be nice, but just to have the information on deprecations in one place would be very nice.

1 Like