The ansible-core project is still releasing 2.16 versions for downstream purposes even though 2.16 is EOL upstream. I removed 2.16 from the tagger script in the ansible/ansible-documentation repo back in November when 2.17 reached EOL. However since then core have released v2.16.15 and v2.16.16.
It probably makes sense to keep the tags in the ansible-documentation repo in sync, even though 2.16 is EOL upstream. I’ve created a PR to add that version back to the tagger script. If you have any thoughts on this, please reply either here or in the PR comments.
Another question might be re-publishing the 2.16 docs. It should be possible to build the docs by manually triggering the workflow even though all the build requirements haven’t been updated recently. I’m not sure if it’s worth going back and enabling workflows to bump dependencies for 2.16 and so on. We should be able to just build 2.16 docs as needed.
Keeping the tags make sense. I approved the PR for that. As for rebuilding the docs manually, I think that makes sense as long as the Core team agrees and we only build the core version of the docs (i.e., the version without community package docs and collection indices from Ansible 9 which is definitely EOL).
I’m wondering why we shouldn’t do a re-build of the Ansible 9 docs. After all, Ansible 9 depends on ansible-core >= 2.16, < 2.17, so when installing Ansible 9 now you get the new feature as well. And at some point we might have to rebuild the Ansible 9 docsite anyway for technical reasons, and instead of only adding the new feature at a random point in the future (when we do a rebuild for other reasons) I think it would be better to do a rebuild now so that users of the EOL Ansible 9 can at least look at the documentation of all features of it.
Or do we want to modify the documentation build process to stick to the latest released ansible-core version that didn’t have the feature? That could be more tricky since the docs build process for the ansible-core and the ansible docs right now doesn’t allow that distinction.
If there are new 2.16 releases, I think the documentation should be updated. Even if core EOL’d 2.16 upstream officially, they did publish new releases. The documentation should reflect those new releases IMHO.
@felixfontein Thanks for raising the question of re-building the Ansible 9 docs, also. At the spur of the moment I should say no. But I don’t think I understand the pros and cons yet.
Thanks for the feedback everyone. I’ve merged that PR to update the tagger script and kicked off a run so all the 2.16.* tags should now be synced between core and the docs repo.
For the core 2.16 docs, I checked in the Read the Docs dashboard. That version is active and hidden, which means it should continue to build when a commit is pushed but the version is not visible from search results or the flyout menu (docs on version states). For good measure I also triggered a build of 2.16 while I was in the dashboard.
[Edit: I should also have mentioned that the .readthedocs.yaml config is in the ansible/ansible-documentation repo. This means that the Read the Docs build is triggered on commit to the devel and stable-* branches in that repo, not in the ansible/ansible repo. So a manual trigger is necessary for older core docs.]
I also kicked off a run of the Ansible 9 docs that will deploy to GitHub pages. I’ll take a look through the logs and generated docs later and update this thread if I spot anything weird. Since we’re not bumping those doc build dependencies I’m not sure if there will be any issues there or oddities with the output. Maybe not but we’ll see.
In any case this is a decision for the SC so I def won’t publish without an ack.
I also didn’t notice anything too suspicious in the logs for the Ansible 9 docs build other than the usual warnings that have been around for ages. So I would say it’s fine to republish the Ansible 9 docs and keep things in sync with core docs. Maybe there are other considerations related to the package builds that I’m not thinking about though.
Yes, ALLOW_BROKEN_CONDITIONALS is the new feature added to ansible-core 2.16.16, so it’s currently missing from the ansible-core 2.16 and Ansible 9 docs.
Also it is quite strange that it says “version added: 2.16” (which means 2.16.0) and not “version added: 2.16.16”, since it’s quite a big difference. The same problem is true stable-2.18, where the feature was added in 2.18.13 and not 2.18.0.
Yes, this looks strange… probably even wrong. I don’t like to ping all of @Core, but in this case I’ll do because I really want to know why it’s 2.16 / 2.18 instead of 2.16.16 / 2.18.13.
Maybe there’s a good reason, but if there is I’d like to know it.
mostly because we almost never do feature releases in minor versions, this is an exception and I’m not sure if all the tooling will work with minor versions, that needs to be tested.
No objections, but keep in mind ansible-core is part of the Red Hat AAP 2.6 release, so what’s the plan for future 2.16 releases? The AAP lifecycle page has core 2.16 lasting into 2028. So my recommendation is to make a policy decision now. Are we signing up for a manual 2.16 core docs update once a month (if there is a release of core)? Are we signing up for an Ansible 9 docs update or was this a once-off because core added a feature?
fwiw, 2.16 will be the gift that keeps on giving from a downstream Support perspective. It is supported within limited contexts in RHEL10 also, until EOL of RHEL10 which is something crazy far off like 2035. Generally speaking it should only be getting critical cve fixes going forward, but we have a few planned things here and there to do to set us up for these crazy long timelines, so we’ll see a few more 2.16 changes rolling out over the next 6 months or so.
I’ve kicked off a build of the Ansible 9 docs to keep things in sync. However I feel like this instance should be kind of a once-off, especially if 2.16 is going to keep offering new delights into the next decade.
May I suggest that we add a banner to the Ansible 9 docs? We can inform users that the community docs are no longer maintained. If they are RHEL 10 users, they should refer to the 2.16 docs for latest updates. All other users are encouraged to upgrade to a more recent version of Ansible 9.
I think that would help users find docs for any new stuff in 2.16 as well as help from revisiting this conversation the next time one of those gifts lands.
I would argue the other way: the ansible-core 2.16 and Ansible 9 docs should be updated if a new version of ansible-core 2.16 is released that has new features / breaking changes / …
I guess in the end we’ll need to vote on this (as this is a policy decision for the @SteeringCommittee), and how we want to handle this in the future for other Ansible / ansible-core releases.
I guess the choices are:
Update Ansible X docs (after its EOL) if the corresponding ansible-core version has new releases that contain new features, breaking changes, or other changes that are important to be documented.
Once an Ansible version is EOL, add the EOL banner (as before) and extend it to redirect users to the ansible-core docs if they want updates for new ansible-core releases that happen.
Keep the EOL banner as-is and do not decide on a policy. (I think this would be the worst option, but it’s also a valid option…)
Thanks for the question and apologies for not explaining myself there.
I was thinking about the need to keep build dependencies up to date on the stable-2.16 branch of the docs repo as well as the need to do things like documenting the exception for community doc builds and coordinating the manual updates whenever core 2.16 adds new features and so on.
Although maybe we can trigger doc builds when new 2.16 tags are created. I’m also not really sure what the implications are for collection docs in the Ansible 9 package. Just thinking out loud though and throwing my 2c in the mix.
I certainly do agree that it’s a steering committee decision.
