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”]((INJECT_FACTS_AS_VARS is defaulting to False in 2.24 - #31 by bcoca), “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.)