search

CircleCI-Public / orb-tools-orb

Various tools for authoring and publishing CircleCI orbs
https://circleci.com/orbs/registry/orb/circleci/orb-tools
MIT License
51 stars 74 forks source link

Made the `v` in version tag optional #155

Closed Gaardsholt closed 1 year ago

Gaardsholt commented 2 years ago

Seen as the v in the version tag is not used for anything, I made it optional

KyleTryon commented 2 years ago

Hello @Gaardsholt

While the v is not used in the orb's version number, it is the standard convention for code releases and specifically git tags. Here is the snippet from semver.org

Is “v1.2.3” a semantic version?

No, “v1.2.3” is not a semantic version. However, prefixing a semantic version with a “v” is a common way (in English) to indicate it is a version number. Abbreviating “version” as “v” is often seen with version control. Example: git tag v1.2.3 -m "Release version 1.2.3", in which case “v1.2.3” is a tag name and the semantic version is “1.2.3”.

Following these standard conventions makes it easier to integrate with additional release tooling outside of the orb-tools-orb, there are some users who bootstrap their orb publishing using NPM utilities.

My worry with leaving it optional is leaving the possibility to accidentally mix-and-match tags in the same code repo, where some releases start with a v and others do not.

My suggestion would be for users to make a decision to fully adopt or explicitly remove the v.

My thinking would be to leave this in place, and allow users to manually modify their config as you have. I do see however there is a bit of support for this feature so I'd love to hear from folks their thoughts.

Gaardsholt commented 2 years ago

@KyleTryon My thinking is that this change just give people more options, without breaking it for anyone. People can then decide to use it with or without v - some organizations might have chosen to use tags without the v, but then they are forced to use it with v if they wanna use this orb.

OrKarstoft commented 2 years ago

Hi @KyleTryon

I just want to point out that in the snippet from semver.org, prefixing a semantic version with a "v" is a common way to indicate it is a version number.

... prefixing a semantic version with a “v” is a common way (in English) to indicate it is a version number. Abbreviating “version” as “v” is often seen with version control. ...

I agree with @Gaardsholt that this solution plainly gives people back the choice to use v or not. As it is now there is no choice. People are forced to use v no matter their preferences, agreement in organization/team etc.

KyleTryon commented 2 years ago

My thinking is that this change just give people more options, without breaking it for anyone. CC @Gaardsholt My issue with having it as optional, is this means you will publish on both, tags with and without the V. I believe that having the v or not is a choice but you should ideally pick one of these conventions and sick with that convention.

My thinking is, we should offer one sensible default, but the user can absolutely customize to their use-case as you have here by modifying the regex for their personal use-cases.

Gaardsholt commented 2 years ago

My thinking is, we should offer one sensible default, but the user can absolutely customize to their use-case as you have here by modifying the regex for their personal use-cases.

If we give people the option to do their own regex, won't that cause problems when doing the publish? I am guessing that the CircleCI Orb Registry expect the version to be in the form of [Major].[Minor].[Patch]

https://circleci.com/docs/orb-concepts#semantic-versioning

Gaardsholt commented 1 year ago

@KyleTryon any updates on this one?

KyleTryon commented 1 year ago

@KyleTryon any updates on this one?

My official recommendation is to leave the choice up to the user, but start with a strict default setting.

Each individual user may modify the regex within the config as you have here. Making the regex less strict does not make for a better experience, the user must choose the best regex string for them. By default, in following GitHub practices, we will leave the V but will encourage you to make any modifications to your config that best suit your pipeline and patterns.

Alternatives to resolving this issue may be with better documentation or possibly an additional question line in the orb init command which would allow you to select which tagging scheme you want to be enabled for you by default.