Insert ansible-core version in the porting guide #397
Conversation
|
The output can be seen in ansible-community/ansible-build-data#100. |
|
LGTM |
|
Nice! |
| builder.add_raw_rst( | ||
| # noqa: E501 | ||
| "\n" | ||
| f"Ansible {version} is based on Ansible-core {base_version}." |
There was a problem hiding this comment.
ooh, a wordsmithing question from gundalow!
There was a problem hiding this comment.
It's the same formulation that we used in the past. "includes" is the language which we use in other places, though some folks don't like that (https://groups.google.com/g/ansible-project/c/XKOuAhD6pk0/m/9fCLXFiTBAAJ) and technically they are right. It depends on whether you look at it from POV of Python packaging, or from POV of an end-user.
There was a problem hiding this comment.
Given that comment in google groups, I'm not sure 'based on' would be considered correct. Perhaps it is "Ansible foo also installs ansible-core bar"?
If that's a bit too much word bikeshedding, I'm quite happy to have based on.
There was a problem hiding this comment.
I think we need to decide at some point what we mean by the "Ansible (PyPi) package". If we mean the set of community collections, with a dependency on ansible-core, then we should throw out all ansible-core specific parts of the docs, including the ansible.builtin plugin documentation, from the Ansible docsite (and just have it in the ansible-core docsite). This is basically what that comment in google groups is asking for. Then we should write something like "depends on". If we on the other hand consider Ansible a big package which includes ansible-core, then we should use "based on" or "included". This is what we decided to do so far, and also what the docsite describes (by including the ansible-core docs in it).
There was a problem hiding this comment.
Docs are most usable when they reflect the user experience. If I install Ansible (the PyPI package), I get ansible-core plus the set of community collections, right? And I don't have to choose a version or even confirm a version of ansible-core? If that's correct, then I'd still vote for "includes" here, because that matches what the user experiences. Yes, it can be overridden. But that takes an extra step. As a user, I'd rather have one set of docs that's correctly versioned for what I have installed, instead of having to confirm which version of ansible-core I have installed, then finding the right version of the docs for ansible-core after I've found the right version of ansible and its docs.
We can certainly add information about installing other versions of ansible-core. We can even add a sentence or two after each mention of Ansible "including" ansible-core that clarifies the mechanism and the fact that it can be overridden ("When you pip install ansible the requirements.txt file automatically installs the associated version of ansible-core, but the ansible-core package is built and distributed separately on PyPI. You can install a different version of ansible-core by . . . "). However, my sense is that for most users version n.n of Ansible "includes" version n.n of ansible-core, because it installs it for them.
If we want to make the user experience more modular, we could make the ansible-core install step separate. But for the average user, my guess is that would be a barrier to use, not an opportunity for greater power or flexibility.
There was a problem hiding this comment.
If we want to make the user experience more modular, we could make the ansible-core install step separate.
@acozine you can already have the 'more modular' approach now by installing ansible-core directly and using ansible-galaxy collection install to install the collections you want.
But for the average user, my guess is that would be a barrier to use, not an opportunity for greater power or flexibility.
I agree.
There was a problem hiding this comment.
I'm +1 for merging this as is.
There was a problem hiding this comment.
Ok, then let's merge this as-is and potentially change this later. Thanks everyone!
|
@briantist @samccann @acozine @gundalow thanks for reviewing this! |
Fixes #396.