# Adding a banner to docs about templating changes in core-2.19 **URL:** \ **Category:** Project Discussions\ **Tags:** documentation, templating, community-wg, dawgs-meeting\ **Created:** [May 1, 2025, 3:30pm UTC](https://forum.ansible.com/t/adding-a-banner-to-docs-about-templating-changes-in-core-2-19/42332 "2025-05-01T15:30:10Z")\ **Posts on this page:** 15\ **Page:** 1
**Author:** ![samccann](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/samccann/32/18_2.png) [@samccann](https://forum.ansible.com/u/samccann)\ **Post date:** [May 1, 2025, 3:30pm UTC](https://forum.ansible.com/t/adding-a-banner-to-docs-about-templating-changes-in-core-2-19/42332/1 "2025-05-01T15:30:10Z")
Hey folks - So I admit, the core 2.19 changes have me worried. I know we have the data-tagging tag here and loads of project discussions, but I worry we haven’t hit our users with this info. One idea that popped up was to add a banner to the top of the docs to give people the heads-up about this. I was thinking for devel and core-2.19/Ansible 12. Something like: `This release has made significant templating changes that enable reporting of numerous problematic behaviors that went undetected in previous releases, with wide-ranging positive effects on security, performance, and user experience. Use to understand where you may need to update your playbooks and roles.` So I’m looking for opinions on this, better wording, better ways to get the news out to our users, etc. ---
**Author:** ![chris](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/chris/32/293_2.png) [@chris](https://forum.ansible.com/u/chris)\ **Post date:** [May 1, 2025, 3:33pm UTC](https://forum.ansible.com/t/adding-a-banner-to-docs-about-templating-changes-in-core-2-19/42332/2 "2025-05-01T15:33:28Z")
From my very limited testing with `fallible` I think you are right to be worried… Could we convince @geerlingguy to test his roles against `2.19` to see if the new [data tagging](https://forum.ansible.com/t/data-tagging-preview-and-testing/40759) breaks lots of things? I can’t think of a better way to get the word out… 😉 ---
**Author:** ![sivel](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/sivel/32/1198_2.png) [@sivel](https://forum.ansible.com/u/sivel)\ **Post date:** [May 1, 2025, 3:46pm UTC](https://forum.ansible.com/t/adding-a-banner-to-docs-about-templating-changes-in-core-2-19/42332/3 "2025-05-01T15:46:19Z")
I know I have a potentially different POV here, but I recommend caution of saying things like “breaks lots of things”. I totally get what most people mean, but there are many who don’t fully understand what is happening, and this creates a lot of FUD. I realize that describing that a playbook no longer fully completes successfully as it did on an older version of core can most easily be called “breaking”. However, there are important distinctions to be made about places where playbooks were doing something that could also be described as imprecise or even dangerous, which is where many of the changes in 2.19 are coming from. If we keep approaching things by saying “i’m worried” or “2.19 breaks a lot of things”, we’re doing a disservice to what 2.19 is trying to accomplish. ---
**Author:** ![geerlingguy](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/geerlingguy/32/11288_2.png) [@geerlingguy](https://forum.ansible.com/u/geerlingguy)\ **Post date:** [May 1, 2025, 3:51pm UTC](https://forum.ansible.com/t/adding-a-banner-to-docs-about-templating-changes-in-core-2-19/42332/4 "2025-05-01T15:51:03Z")
The easiest way I would test with any of my content is to grab one of my playbooks that has full GitHub Actions CI and still installs Ansible separately (a lot of my test environments use Docker images, so the dependency chain is a little more annoying), and force an install of 2.19 instead of ‘current stable’. For example, my mac-dev-playbook: [mac-dev-playbook/.github/workflows/ci.yml at master · geerlingguy/mac-dev-playbook · GitHub](https://github.com/geerlingguy/mac-dev-playbook/blob/master/.github/workflows/ci.yml) From an end user’s perspective “my simple-ish playbook doesn’t run anymore on 2.19” would definitely equate to “breaks things”. I know Ansible doesn’t do ‘semantic versioning’ like I think of it, but I wouldn’t expect non-hacky playbooks to have problems unless there’s a 3.0 release. (I haven’t followed discussions around data-tagging, so not sure exactly where the concern lies). ---
**Author:** ![nitzmahone](https://avatars.discourse-cdn.com/v4/letter/n/c5a1d2/32.png) [@nitzmahone](https://forum.ansible.com/u/nitzmahone)\ **Post date:** [May 1, 2025, 4:10pm UTC](https://forum.ansible.com/t/adding-a-banner-to-docs-about-templating-changes-in-core-2-19/42332/5 "2025-05-01T16:10:56Z")
I’d also suggest referring generically to “templating” instead of “jinja2” in whatever wording is chosen- the changes are nearly all about changing the way Ansible does things internally around templating, and while yes, our underlying templating engine is Jinja2, I imagine members of that project might take umbrage at having their name pulled in here. ---
**Author:** ![samccann](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/samccann/32/18_2.png) [@samccann](https://forum.ansible.com/u/samccann)\ **Post date:** [May 1, 2025, 4:22pm UTC](https://forum.ansible.com/t/adding-a-banner-to-docs-about-templating-changes-in-core-2-19/42332/6 "2025-05-01T16:22:10Z")
Updated the wording to just say ‘templating’ instead. Thanks for the feedback so far everyone! ---
**Author:** ![samccann](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/samccann/32/18_2.png) [@samccann](https://forum.ansible.com/u/samccann)\ **Post date:** [May 1, 2025, 4:30pm UTC](https://forum.ansible.com/t/adding-a-banner-to-docs-about-templating-changes-in-core-2-19/42332/7 "2025-05-01T16:30:42Z")
The porting guide had some great intro text so I put that in the proposed banner at the top of this thread. Please take another look and thanks everyone for the quick feedback! I might need to trim the level of text as it’s getting a bit long for a banner, but let’s see what y’all think first. ---
**Author:** ![felixfontein](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/felixfontein/32/7530_2.png) [@felixfontein](https://forum.ansible.com/u/felixfontein)\ **Post date:** [May 1, 2025, 7:28pm UTC](https://forum.ansible.com/t/adding-a-banner-to-docs-about-templating-changes-in-core-2-19/42332/8 "2025-05-01T19:28:31Z")
I like the proposed banner text! One possible change would be the second half of the last sentence: “to ensure your Ansible content is compatible”. I don’t really like that formulation since you need to do a lot more than reading the porting guide to figure out whether your content is compatible. Reading the porting guide enables you to understand the pitfalls/potential problems though, and that helps you to understand breakages. An alternative formulation could be “to understand potential compatibility issues your Ansible content could have”, though I don’t like that either since it’s too complex IMO. Regarding “breaking” and “I’m worried”: I understand why @sivel thinks these are dangerous, **but** : every major ansible-core release has breaking changes, IMO that’s normal - and often it’s also good, because these breaking changes fix something that wasn’t great. This is especially true for Data Tagging: it is making things **a lot** better (easier to understand, less error-prone, more predictable, more logical, …). But at the same time, the percentage of potentially affected playbooks/roles out there that could be broken by the breaking changes in ansible-core 2.19 is **a lot** higher than for usual major ansible-core releases. At the same time it’s a lot harder to figure out which parts break without simply (re-)running the playbooks (in staging environments, or with check mode in production). This is the part that is definitely worrying, if mainly for the reason that many users might not notice that something big changed and simply assumes “it will mostly just work, as always”, until it suddenly does not. If you switch from ansible-core \< 2.19 to ansible-core 2.19 in production without testing first the chance of things really breaking is higher than for other new major releases. I’m definitely worried that some users will only find out that way about breaking changes, and will blame it on Ansible without understanding what is happening (and that they basically screwed it up themselves by not properly testing when updating to a new major release). (The solution to that is definitely **not** to remove Data Tagging from 2.19 though.) ---
**Author:** ![russoz](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/russoz/32/127_2.png) [@russoz](https://forum.ansible.com/u/russoz)\ **Post date:** [May 1, 2025, 7:54pm UTC](https://forum.ansible.com/t/adding-a-banner-to-docs-about-templating-changes-in-core-2-19/42332/9 "2025-05-01T19:54:26Z")
I’ll just say it: IMHO this release should be numbered 3.0, to: - indicate clearly the magnitude of the change, and with that… - … catch the attention of the users Major version bump or not, the banner is clearly a good way to advertise the changes. As of the wording, I understand the urge not to be misunderstood and to prevent FUD, but I don’t think that goal is achieved unless we say things straight, as they are. And as pointed out before, the fact here is that the changes potentially (likely?) break existing playbooks. ---
**Author:** ![samccann](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/samccann/32/18_2.png) [@samccann](https://forum.ansible.com/u/samccann)\ **Post date:** [May 1, 2025, 8:11pm UTC](https://forum.ansible.com/t/adding-a-banner-to-docs-about-templating-changes-in-core-2-19/42332/10 "2025-05-01T20:11:50Z")
How about changing the last sentence to `Use to understand where you may need to update your playbooks and roles`. Then we could potentially add a sentence to the intro to the porting guide to say `We recommend you test your playbooks and roles in a staging environment with stable-2.19 to determine where you may need to make changes.` ---
**Author:** ![felixfontein](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/felixfontein/32/7530_2.png) [@felixfontein](https://forum.ansible.com/u/felixfontein)\ **Post date:** [May 1, 2025, 8:21pm UTC](https://forum.ansible.com/t/adding-a-banner-to-docs-about-templating-changes-in-core-2-19/42332/11 "2025-05-01T20:21:09Z")
> [@samccann](#): > > How about changing the last sentence to > `Use to understand where you may need to update your playbooks and roles`. Sounds good to me! > [@samccann](#): > > Then we could potentially add a sentence to the intro to the porting guide to say `We recommend you test your playbooks and roles in a staging environment with stable-2.19 to determine where you may need to make changes.` 👍 ---
**Author:** ![samccann](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/samccann/32/18_2.png) [@samccann](https://forum.ansible.com/u/samccann)\ **Post date:** [May 12, 2025, 4:23pm UTC](https://forum.ansible.com/t/adding-a-banner-to-docs-about-templating-changes-in-core-2-19/42332/12 "2025-05-12T16:23:04Z")
PR created for the docs banner - [Add banner for templating to devel docs by samccann · Pull Request #2627 · ansible/ansible-documentation · GitHub](https://github.com/ansible/ansible-documentation/pull/2627) ---
**Author:** ![russoz](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/russoz/32/127_2.png) [@russoz](https://forum.ansible.com/u/russoz)\ **Post date:** [June 6, 2025, 11:11am UTC](https://forum.ansible.com/t/adding-a-banner-to-docs-about-templating-changes-in-core-2-19/42332/13 "2025-06-06T11:11:15Z")
I am a bit late, I know, apologies. I think that wording better conveys the point we are trying to make. ---
**Author:** ![mariolenz](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/mariolenz/32/108_2.png) [@mariolenz](https://forum.ansible.com/u/mariolenz)\ **Post date:** [June 6, 2025, 3:39pm UTC](https://forum.ansible.com/t/adding-a-banner-to-docs-about-templating-changes-in-core-2-19/42332/14 "2025-06-06T15:39:08Z")
I think the current wording is OK, although I’m not too sure about the positive effects on user experience since the changes might (sorry @sivel!) possibly _break_ existing playbooks 😏 I think there might be some people who won’t agree, although I agree with this generally and especially in the long run. So let’s keep it as-is. However, should we mention where people can get help? Like the forum in general, a specific forum thread or a forum tag people can use if they have any questions? Or chat? Although the forum would be better since we’ve moved a lot of conversation to it. What do you think? ---
**Author:** ![Lyle\_McKarns](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/lyle_mckarns/32/8142_2.png) [@Lyle\_McKarns](https://forum.ansible.com/u/Lyle_McKarns)\ **Post date:** [June 6, 2025, 4:24pm UTC](https://forum.ansible.com/t/adding-a-banner-to-docs-about-templating-changes-in-core-2-19/42332/15 "2025-06-06T16:24:38Z")
> [@mariolenz](#): > > However, should we mention where people can get help? Like the forum in general, a specific forum thread or a forum tag people can use if they have any questions? Or chat? Although the forum would be better since we’ve moved a lot of conversation to it. What do you think? I like the idea of a specific tag (and I agree that the forum is superior to chat for this, because a lot has moved here AND is much more searchable for people with the same problem)