Unclear Oolite Version Numbers

[oocube]

Problem:

Today Oolite Version Numbers look like this:

oolite-1.93.0.7823-260429-7b8fba2-x86_64.AppImage
oolite_test-1.93.0.7808-260426-d4a1548-x86_64.AppImage

The components of this version string are:

• The string "oolite"
• optionally a markup that this is the test or debug build
• 1.93.0 - the 'official', manually maintained version number
• an automatically calculated version number - the number of commits since start of the project on this branch
• the build date to accomodate for a nonsequential version number - not granular enough if multiple builds happen on the same day
• the Git commit hash

All these items are not good enough to decide what version you are running, or which is newer. Why so?

During development, all versions generated have the 1.93.0 equal, unless something is officially released as stable.
While we develop on different branches, the automatically calculated version number is not a sequence any more. It can even go backwards when we squash commits or move the branch pointers.
Thus the only item that uniquely marks up a build is the commit hash. A nuisance for humans to decide which of the builds is newer, or which of them came from even a different repository.

Alternative:

Let's look at semantic versioning - it is described at https://semver.org/. This scheme is already in use on OoliteStarter, version numbers there look like this:

v0.1.34
v0.1.35-kaleyard.17
v0.1.35-kaleyard.18
v0.1.35-kaleyard.19
v0.1.35-kaleyard.20
v0.1.35

Users can - without much thinking - identify which version comes from a branch and which is the official release. Users and computers can easily sort the versions to find out which is newer.
What this scheme does not cover, however is if a build came from a different repository.

Suggestion:

Let's change to semantic versioning plus add a feature to markup builds that come from a different repository. This markup could be as simple as replacing the project name string "oolite" with "customoolite", or as smart as adding the repository name (this would likely only work if built on Github).

Apart from just changing our build scripts we also need to change our behaviour. Commits on the master branch would always result in a new release. Development would have to happen on a feature branch, and every PR to master is a release already. Pre-release code freezes would become unnecessary. The time-to market for bugfixes or features would shrink, the agility of the project would pick up speed at the same time.

[oocube]

I created the branch 'semver'. It contains one job 'common' that executes before all the others.
So far it calculates the semantic version number and sets environment variables. These variables are visible in the log output but otherwise unused. No impact for the time being.

We can test it for some time on different branches and forks and - if satisfactory - start using the version number to label the oolite builds.

The environment variables we need to look at are all the variables starting with 'GitVersion_' and 'PROJECTNAME'.

GitVersion_SemVer=1.93.1-semver.1
PROJECTNAME=oolite

[oocube]

I forked oolite and triggered the Github builds. Version information:

GitVersion_SemVer=1.93.1-semver.1
PROJECTNAME=OoliteFork

With that I'd like to merge to master, to see whether version numbers are consistent across branches and finally enable them in the build scripts.

[oocube]

@mcarans I am open to use some other tool (see discussion in #619). However I feel that you focus on technology that is hidden away in a container. On top of that further development requires commit messages to be written in a specific format - something that all committers need to consistently adhere to.

Since I already thought about a trial period we could actually check if GitVersion and your alternative could run in parallel, just generating version numbers and placing them in the log. From that all dev team members can see which pattern is preferred and vote.

[mcarans]

For completeness and in case the branch is lost, here is what I wrote there to which the comment above is a response:

Yes I'll need to look into ensuring the version doesn't get repeatedly incremented.

I'm learning more about this topic via AI. The latest way to do things which I think you might like are "conventional commits".

"Conventional Commits is a lightweight specification for your commit messages that makes them both human-readable and machine-processable. It has largely become the "modern" industry standard because it replaces the "guesswork" of branch-based versioning with a data-driven, automated workflow.

1. The Structure

The format is simple: <type>(<scope>): <description>

• feat: A new feature (maps to a Minor version bump).
• fix: A bug fix (maps to a Patch version bump).
• BREAKING CHANGE (or adding a ! after the type): A change that breaks backward compatibility (maps to a Major version bump).
• Other types: chore, docs, style, refactor, perf, test (usually don't trigger a version bump).

2. Why is it considered the "Most Modern" way?

While branch-based versioning (like GitVersion) was popular for a long time, the industry has shifted toward Conventional Commits for several reasons:

A. Automated Versioning & Changelogs

Because the "intent" of the change is baked into the commit message itself, tools like semantic-release or release-please can:

• Scan your git history.
• Determine if the next version should be 1.0.1 or 1.1.0.
• Automatically generate a CHANGELOG.md that lists exactly which features and fixes were added.

B. Platform Agnostic

Unlike GitVersion, which requires a .NET runtime or complex configurations to understand your branching strategy, Conventional Commits works anywhere. Whether you are in a C++ project using Meson, a Web app using Node, or a Systems tool in Go, the logic remains identical.

C. Better for Trunk-Based Development

Modern teams are moving away from long-lived feature branches (GitFlow) toward Trunk-Based Development, where everyone pushes to main frequently.

• Branch-based versioning struggles here because there are no "feature branches" to look at.
• Conventional Commits thrives here because every single commit clearly states its impact on the version number."

AI also suggested a tool called GoReleaser which despite the name, is actually a tool that both handles version and publishes releases on multiple platforms in multiple package managers (msix, arch, deb, rpm, flatpak etc.) regardless of language. That could be something to look into in future but possibly a bit ambitious now.

The svu tool I mentioned previously also supports "conventional commits".

Which approach works best for Oolite development is probably best opened to a wider discussion as these approaches won't work unless there is buy in from devs.