semver with identifiers & Development/Branching Strategy

[rbuckland]

Hi @bvieira

We are using sv4git, thank you. Good, concise tool.

Have you any thoughts on supporting the extra identifiers to semver for a version
eg:

• 4.5.1-rc1
• 4.5.1+004
• 4.5.1-feat4+33

Each above would be valid semver, of course, versioning and a whole companies development/branching workflow comes into play.

# ref: https://semver.org/
<valid semver> ::= <version core>
                 | <version core> "-" <pre-release>
                 | <version core> "+" <build>
                 | <version core> "-" <pre-release> "+" <build>

I am keen to work on design and implementing the required features

[rbuckland]

a few things I think need to be changed

sv4git is using https://github.com/Masterminds/semver

sv4git/sv/semver.go

Line 20 in d76920b

v, err := semver.NewVersion(version)

When an existing version (from tag) is read in, the "extended" formats are supported no worries, and sv4git, dtermines the next version perfectly.

host in ~/pr/bi/SE/gitsv-testing on  main 
08:14:28  ❯ git tag -l
0.2.3+11

host in ~/pr/bi/SE/gitsv-testing on  main 
08:14:33  ❯ git-sv nv 
0.2.4

So the problem becomes ..

1. "what extra details" to apply as context to the version pattern (currently %d.%d.%d)
2. and when do they apply

What I am thinking is

1. change the "pattern" to a go template
2. inject into that template, a context object that has
   • semve - https://github.com/Masterminds/semver/blob/49c09bfed6adcffa16482ddc5e5588cffff9883a/version.go#L46
   • git context (branch, type of change) https://github.com/bvieira/sv4git/blob/master/sv/git.go#L22

"{{.semver.major}}.{{.semver.minor}}.{{.semver.patch}}{{.semver.metadata}}"

• Release Candidate support
  Assumption - rc, or feature, should be derived off of branch
  (I am not a go programmer) - add some functions in the template context, so we can use the .git.branch to derive some "extra"semver identifier

• Build Number style
  harder :-D
  I think.. if a tag, on the branch has a build number, it gets incremented, only if the commit doesn't bump the semver (via approved semver)

[bvieira]

Hey, thanks for using sv4git!! ❤️

It's not common for me to use the extra identifiers, so, could you please explain your use case? How do we know when this tag should be a release candidate or a build or any other prerelase?

Maybe it could be some kind of flag in the git sv tag command..
Or are you suggesting that if the tag is executed in a specific branch or a branch pattern it should automatically generate a release candidate (or another prerelease)?

[rbuckland]

could you please explain your use case?

Two use cases for example. These examples are of / for other languages, not go.

1. Microservices - multiple components.

A team of developers building software, in a poly-repo (not mono repo) made up of 8 micro-services. a few of the micro-services share components, libraries; some do not. All components when built are published via the internal repository system (github releases for example)

microservice1/ v6.0.0
    shared lib A v1.0.2
    shared lib B v3.9.0

Developer is working on a bug that affects the microservice 1 - but to fix it they need to fix and update the shared-lib B also.
The developer starts a new branch on shared lib B and publishes v3.9.1-bug903

then starts a new branch on microservice1, updates the code using the new fix sharedlib B v3.9.1-bug903 (big complicated software that needs to be bundled with sharedlibB and tested) ... publishes microservice1/v6.0.1-bug903

once all testing is complete and it's a success, the developer creates PRs of shared lib B and microservice1, merging to main, and the new versions are published.

1. RC Candidates

The developers release periodically to their clients, a new ProductX-v5.0.0-rc1 (rc2 rc3 etc)
To do this they use a release branch, and only when the release is merged to main is there a version published, without the -rcX suffix.

[rbuckland]

Good questions @bvieira

The use of extra identifiers in a version:

1. must align to semver (of course)
2. is very much tied to an organizations process and methods of their SLDC (mono repo, poly-repo, main branch, feature branch, dev branch) - the list is extensive.

When and what an organization uses as extra metadata can be quite complex.
Your suggestion of a config parameter avoids that problem, makes a lot of sense.

Complex tagging logic can be avoiding for the moment, (topics like)

• if MAJOR.MINOR.PATCH+BUILDNUM - when does the buildnum get incremented ?
• if MAJOR.MINOR.PATCH-BRANCH-NAME - how do we extract the concise portion of the branch name (answer: use go template to regex off the portion you want)

I have pondered this a little and have two suggestions that may spark extra thought,
Both, are driven off using a command line parameter to select an alternative profile

git sv tag --profile=with-branch

Option 1 - just add additional custom tagging profiles

tag:
    default:
        pattern: {{.semver.major}}.{{.semver.minor}}.{{.semver.patch}} # Default pattern used to create git tag.
    <custom-name>:
       pattern: {{.semver.major}}.{{.semver.minor}}.{{.semver.patch}}+{{.git.branch}} # Default pattern used to create git tag.

example

tag:
    default:
        pattern: {{.semver.major}}.{{.semver.minor}}.{{.semver.patch}} # Default pattern used to create git tag.
    with-branch:
       pattern: {{.semver.major}}.{{.semver.minor}}.{{.semver.patch}}+{{.git.branch}} # Default pattern used to create git tag.

and then at command line

git sv tag --profile=with-branch

Option 2 - wrap versioning and tag into a profiles.

It opens up looking at the two config settings versioning and tag together as they are directly related.
meaning, this may be easier

versioning: # versioning bump
    default:
        update-major: [] # Commit types used to bump major.
        update-minor: [feat] # Commit types used to bump minor.
        update-patch: [build, ci, chore, fix, perf, refactor, test] # Commit types used to bump patch.
        # When type is not present on update rules and is unknown (not mapped on commit message types);
        # if ignore-unknown=false bump patch, if ignore-unknown=true do not bump version
        ignore-unknown: false
        tag-pattern: {{.semver.major}}.{{.semver.minor}}.{{.semver.patch}} # Pattern used to create git tag.
    with-branch:
        update-major: [] # Commit types used to bump major.
        update-minor: [feat] # Commit types used to bump minor.
        update-patch: [build, ci, chore, fix, perf, refactor, test] # Commit types used to bump patch.
        # When type is not present on update rules and is unknown (not mapped on commit message types);
        # if ignore-unknown=false bump patch, if ignore-unknown=true do not bump version
        ignore-unknown: false
        tag-pattern: {{.semver.major}}.{{.semver.minor}}.{{.semver.patch}}+{{.git.branch}} # Pattern used to create git tag.

Of course, it then takes it to .. what about just clone the whole config under profiles :-)

profile:
  default:
     ...
  with-branch:
    ...