standardize devtools version tags
ssbarnea opened this issue · comments
We should aim to standardize version tags on all our repositories. The current status looks like:
numeric only tags (X.Y.Z)
- molecule
- molecule-podman
- molecule-containers
- ansible-navigator
v-prefixed value (vX.Y.Z)
- ansible (outside our control)
- ansible-lint
- ansible-compat
- vscode-ansible
- ansible-language-server
Considering that ansible is the core product it would make sense to adopt the v-prefixed variants and slowly migrate to these, new tags being using the format, repushing corrected tags for old releases and retiring old tags in the end.
Should we generalize v1.2.3 prefixes?
To ease counting of opinions, please use up-thumb in favour of v-prefix and down-thumb in favour of version tags without v-prefix.
We would likely do not do any renames for historical values when we decide to go for one option or another.
We should use v because traditionally they're used for tags but non-prefixed ones are often used for the version stream branches.
I already started to use v everywhere while not touching existing tags.
Took a quick look at some other platform components:
ansible-builder => numeric
ansible-runner => numeric
content:
ansible.utils: numeric
ansible.netcommon: numeric
cisco.nxos: numeric
cisco.ios: numeric
cisco.asa: numeric
<...> all Supported collections it appears
and upstream platform:
awx: numeric
devtools should generally follow other platform components unless there is a compelling reason not to
https://semver.org/#is-v123-a-semantic-version
Since we follow semantic version I prefer to use a numeric versioning
The version number and the tag are separate items:
Abbreviating “version” as “v” is often seen with version control.
I prefer the v prefix for tags and kinda wish that's what we did for Runner and Builder.
@samdoran Any plans/desire to change runner/builder? I don't have a pref here, just looking for consistency across platform components where possible
We don't have any plans to change things. I was just stating my opinion.
semver.org/#is-v123-a-semantic-version
Since we follow semantic version I prefer to use a numeric versioning
Interestingly, the paragraph you linked specifically demonstrates using v in Git (and having it stripped in other places).
I've decided to do a little research in the wild and it seems like many projects do just that — they have v-prefixed immutable tags. Even the repository of SemVer itself uses these prefixes in every version they've had, consistently: https://github.com/semver/semver/tags.
Some of the other motivations for having prefixes include TAB-completion: https://stackoverflow.com/a/21639868/595220. I haven't thought about this before but it really makes sense that on CLI you'd get a list of tags more easily. Now that I think about it, in the past, this even helped me to dynamically look up Python versions based on the CPython repository: https://github.com/ansible/pylibssh/blob/d080966/.github/workflows/build-test-n-publish.yml#L223.
There's also mentions of ambiguity of the tag vs branch names: https://stackoverflow.com/a/21640164/595220. I even have an example project I maintain — stream/stable branches are 3.6, 3.7, 3.8 but the tags are v3.6.1, v3.7.4, v3.8.0. I know that many projects would prefix the branches with something but I'm mentioning this to demonstrate that it is not always the case.
When working with Git, I normally push for practices that the Git devs advertise (in many regards). So I checked out the manpages (https://git-scm.com/docs/git-tag) and while there's no explicit ask to use a prefix, there's a filtering example that showcases the use of a dashed prefix — git tag --list 'v-*'. Plus there's another example showing a single-char prefix: GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1.
Also, I'd like to note that git tag --sort=-v:refname seems to properly sort the tags regardless of whether they are with or without the prefix.
I've also found a scientific Python ecosystem convention to use the v prefix at https://nsls-ii.github.io/scientific-python-cookiecutter/publishing-releases.html.
It seems like an earlier version of SemVer used to mandate (with a capitalized-MUST in the spec) the v-prefix that the latest one converted into a less strongly worded FAQ paragraph: https://stackoverflow.com/a/2011372/595220.
Also, it's worth noting that the default mechanism of bumping versions in the NodeJS ecosystem is the npm version command that updates package.json, package-lock.json and creates a Git tag. The tag it creates has a leading v regardless of whether the passed CLI arg has it or not.
I've checked a few other high-profile projects in the ecosystem, like CPython or setuptools, and they all use v-prefixes. I've also seen some that don't but I don't have data to say which way is more popular.
I know that it may be nice to align with other Ansible projects but at the moment, after all the research I still feel strongly about having prefixed tags.