linux packageinfo version is inconsistent with git tags

[LW-archlinux]

oolite trunk rev 5083ea4 , sourcebuild using aur packaga

$ oolite-git.sh packageinfo
{
    title = "Oolite core";
    identifier = "org.oolite.oolite";
    
    version = "1.93.0.7945-260611-5083ea4";
<snip>
}
$ 

Looking at src/oolite-git/ShellScripts/common/get_version.sh this could be due to not setting $SEMVER or $PROJECTNAME at build time.

[oocube]

Indeed. These variables are only set in a github build.
It is intentional to identify the builds created with the official CI/CD chain and a self-compiled something.

[LW-archlinux]

That is confusing for users as all are build from the same sourcecode commit so are typically considered to be different builds of the same version .

Currently the package ID as shown by the distro package manager is oolite-git 1.93.1.182.r0.5083ea425-1 ((version is dynamically created by git commands) while the latest trunk release has Oolite 1.93.1-182 .

Is that difference not enough to distinguish between upstream CI/CD builds and downstream builds ?

Any alternative needs to be creatable using a clone of the oolite source repository and show a clear relation between distro package manager info, oolite executable packageinfo and sourcecode version.
What alternative would you suggest for downstream ?

[oocube]

I discussed the version numbers both in the forum and in #616.
It was my intention to bring easier to compare versions into the pipeline and to better distinguish where an artifact was built.

My change involved all that is built in our Github project. Other builds simply stayed on the existing versioning scheme.
Now why do you think it is incorrect?

[mcarans]

@LW-archlinux Does AUR have a standard versioning approach? If it is what you have already implemented, better to stick with that.

If not, since the tool used by CI is gitversion, you may be able to generate a similar version using this package: https://aur.archlinux.org/packages/gitversion. Maybe you could copy oocube's logic from the CI workflow into your CI workflow that generates the AUR package?

I remember looking into gitversion in the source builds but the challenge was that the get_version.sh script is called from multiple places so there was a risk that an incrementing number in the version would keep changing. Also, as I understand it, with gitversion you need a git deep clone. A git shallow clone will not work with it and I don't want to make deep clones a requirement for building oolite locally.

[LW-archlinux]

I've changed the ticket title to reflect that this is a consistency issue.

In the oolite-git PKGBUILD a git clone is used to retireve the oolite sourcecode from https://github.com/OoliteProject/oolite.git
This is a clone of master with all history of the repo.

I then use

git -C oolite-git describe --long --tags | sed 's/^v//;s/\([^-]*-\)g/r\1/;s/-/./g'

to get a version number using the most recent tag (annotated or non-annotated) reachable from the current commit:
archlinux has strict rules what is allowed in pkgver strings (mainly numbers, letters and dots), the sed part of the command takes care of changing not-allowed characters like dashes .

Currently that results in 1.93.1.182.r0.5083ea425 as version string .
1.93.1.182 is the latest tag in the repo , r is a counter that reflects how many commits were merged after the tag was made.
The last part of the pkgver string is the shortened commit hash of the last commit added to master.
Combined this gives a unique number that has a direct relation to the version of the sourcecode that is build .

Note that this method only uses info available from git to get the version.

oolite packageinfo of the build executable gives a very different number . This inconsistency is confusing for users and needs to go.

It's not a problem with Semantic Versioning, but with downstream and upstream numbering for master builds. CI/CD, github workflows and downstream build workflows should follow numbering schemes not dictate them.

This can be solved in 2 ways :

• A. change the version reported by oolite packageinfo to resemble the pkgver string as closely as possible.
• B. change the pkgver function to retrieve the number packageinfo constructs from src/Cocoa/oolite-version.xcconfig and 2 git values.

Best practice for downstream builds is to follow the versioning used/desired by upstream.
What numbering scheme do oolite code owners/developers prefer for master builds by downstream ?

Keep in mind that whichever scheme is chosen this should be valid for all downstream master builds and very likely to be used in bug reports by users of downstream packages .

If B is chosen I can make the necessary changes to the pkgver() myself, for A I need your/upstream devs help.

[mcarans]

AI suggests: "Here is a lightweight script demonstrating how to calculate a GitVersion-style Continuous Deployment version string on a develop branch using pure Git:

#!/usr/bin/env bash

# 1. Get the latest tag and clean it up (assuming vX.Y.Z format)
LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0")
BASE_VERSION=${LATEST_TAG#v} # Strips the 'v' prefix -> "1.2.0"

# 2. Extract Major, Minor, Patch components
IFS='.' read -r MAJOR MINOR PATCH <<< "$BASE_VERSION"

# 3. Simulate GitVersion's 'develop' increment policy (automatic Minor bump)
NEXT_MINOR=$((MINOR + 1))
TARGET_VERSION="${MAJOR}.${NEXT_MINOR}.0"

# 4. Get the branch name and count commits since the base tag
BRANCH=$(git branch --show-current)
COMMIT_COUNT=$(git rev-list ${LATEST_TAG}..HEAD --count 2>/dev/null || echo "0")
SHORT_SHA=$(git rev-parse --short HEAD)

# 5. Format the branch name for SemVer compliance (alphanumeric only)
CLEAN_BRANCH=$(echo "$BRANCH" | sed 's/[^a-zA-Z0-9]/-/g')

# 6. Assemble the SemVer output
# Emulates: [TargetVersion]-[Branch].[CommitCount]+[SHA]
FULL_SEMVER="${TARGET_VERSION}-${CLEAN_BRANCH}.${COMMIT_COUNT}+sha.${SHORT_SHA}"

echo "Calculated SemVer: $FULL_SEMVER"

Expected Output Structure:

If your last tag was v1.2.0, you are on feature/api-auth, and you are 4 commits ahead:

Calculated SemVer: 1.3.0-feature-api-auth.4+sha.7a2b3c4

While it doesn't handle every edge case that GitVersion’s massive configuration engine does (like parsing +semver: breaking out of specific commit logs unless you add a git log --grep step), this native approach covers the core graph-traversal logic perfectly."

The above script also requires a deep clone though.

The meson way to do it is apparently something like this:

project('my_project', 'c', version: '1.92.0')

# This creates a build target that generates 'version.h' from 'version.h.in'
version_h = vcs_tag(
  input: 'version.h.in',
  output: 'version.h',
  fallback: meson.project_version(), # Used if .git doesn't exist (e.g. from a tarball)
  command: ['git', 'describe', '--always', '--tags', '--dirty'] # Optional override
)

# You MUST pass the returned object into your sources so Meson tracks the dependency
executable('my_app', 'main.c', version_h)

The example input version.h.in template:

#ifndef VERSION_H
#define VERSION_H

// Meson looks for the literal string @VCS_TAG@
#define PROJECT_VERSION "@VCS_TAG@"

#endif

What is output:

#ifndef VERSION_H
#define VERSION_H

// Meson replaced @VCS_TAG@ with the output of git describe
#define PROJECT_VERSION "v1.92.0-3-gabcd123"

#endif

Uncommitted changes look like this:

#define PROJECT_VERSION "v1.92.0-3-gabcd123-dirty"

If built from release tarball (not .git) the fallback is used:

#define PROJECT_VERSION "1.92.0"

[oocube]

to get a version number using the most recent tag (annotated or non-annotated) reachable from the current commit: archlinux has strict rules what is allowed in pkgver strings (mainly numbers, letters and dots), the sed part of the command takes care of changing not-allowed characters like dashes .

Currently that results in 1.93.1.182.r0.5083ea425 as version string . 1.93.1.182 is the latest tag in the repo , r is a counter that reflects how many commits were merged after the tag was made. The last part of the pkgver string is the shortened commit hash of the last commit added to master. Combined this gives a unique number that has a direct relation to the version of the sourcecode that is build .

As long as the code that gets compiled is not locally modified I agree this numbering scheme works. It is sufficiently different from the semver approach that I won't bother.

I like the meson handling of uncommitted changes by appending "-dirty", but the AUR versioning scheme seems to not allow that. In our pipeline this is not necessary as it checks out the repository and builds directly - this even happens in multiple places.

Nevertheless, to move on I suggest to calculate the version number the way you suggested, then populate it into SEMVER variable and set PROJECTNAME before calling the build script. That should give you consistent AUR version numbers throughout the build artifacts.

[mcarans]

@oocube Since you mentioned in the other ticket that you like the meson way of doing versions but not the custom aspect of it, I researched further. All meson's versioning is doing beneath the hood is a simple git command that can capture uncommitted changes:

> git describe --always --tags --dirty
1.93.1-7944-1-g5083ea42-dirty

@LW-archlinux Would this work for AUR based on your query above adding --dirty?

> git describe --long --tags --dirty | sed 's/^v//;s/\([^-]*-\)g/r\1/;s/-/./g'
1.93.1.7944.r1.5083ea42.dirty

If we want to capture the branch, then that's straightforward:

> # 1. Get the branch name
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)

# 2. Get the base version string
VERSION=$(git describe --long --tags --dirty 2>/dev/null)

# 3. Check if BRANCH is empty, or if it is just a detached "HEAD"
if [ -z "$BRANCH" ] || [ "$BRANCH" = "HEAD" ]; then
    # Standard format without branch
    FINAL_VERSION=$(echo "$VERSION" | sed 's/^v//;s/\([^-]*-\)g/r\1/;s/-/./g')
else
    # Format with branch injected before the commit info
    FINAL_VERSION=$(echo "$VERSION" | sed "s/-\([0-9]*-g\)/-${BRANCH}-\1/; s/^v//; s/\([^-]*-\)g/r\1/; s/-/./g")
fi

echo "$FINAL_VERSION"
1.93.1.7944.master.r1.5083ea42.dirty

It would be very easy to use the above git command(s) in get_version.sh so that it works across everything CI, flatpak (including its manifest), appimage, NSIS etc. without requiring installing any extra tools.

I'm sure that the AUR guys thought through what would make a good standard more than we have time to. Therefore, I think that I would be happy just adopting AUR's versions throughout oolite since currently AUR is really the only thing that enforces a strict standard.

[LW-archlinux]

adding --dirty doesn't seem to change anything, maybe because the git clone created by makepkg is a read-only clone from https://github.com/OoliteProject/oolite.git ?

git rev-parse --abbrev-ref HEAD 2>/dev/null works and shows master . Adding the branch to the the pkgver() function result should be doable and doesn't violate archlinux VCS package guidelines.

As long as the git commands used to create the version are documented somewhere it will be fine for me.

Wether setting semver / projectname manuall is better then changing getver.sh is your decision.

[mcarans]

adding --dirty doesn't seem to change anything, maybe because the git clone created by makepkg is a read-only clone from https://github.com/OoliteProject/oolite.git ?

git rev-parse --abbrev-ref HEAD 2>/dev/null works and shows master . Adding the branch to the the pkgver() function result should be doable and doesn't violate archlinux VCS package guidelines.

As long as the git commands used to create the version are documented somewhere it will be fine for me.

Wether setting semver / projectname manuall is better then changing getver.sh is your decision.

If there are no local changes then dirty won't be added.

Ok good looks like we have a way to resolve this issue.

[oocube]

I'm sure that the AUR guys thought through what would make a good standard more than we have time to. Therefore, I think that I would be happy just adopting AUR's versions throughout oolite since currently AUR is really the only thing that enforces a strict standard.

So did the semver guys. But the goals for both version schemes are different. Semver version numbers are intended for software development where you want to easily remember version numbers even across branches. We do not develop on a single branch.

If we switched to AUR, the whole point for me to switch to Semver would be lost. Strictly numerical version numbers is what we used to have all those years. We would simply go back to that state. That is far bigger impact for me than missing the
'-dirty' flag.

[mcarans]

So did the semver guys. But the goals for both version schemes are different. Semver version numbers are intended for software development where you want to easily remember version numbers even across branches. We do not develop on a single branch.

If we switched to AUR, the whole point for me to switch to Semver would be lost. Strictly numerical version numbers is what we used to have all those years. We would simply go back to that state. That is far bigger impact for me than missing the '-dirty' flag.

Our final releases will presumably always look like this whatever system we use: https://github.com/OoliteProject/oolite/releases/tag/1.92.1.0

So what we're talking about are the versions used by intermediate releases we use for testing. The old versions looked like this: https://github.com/OoliteProject/oolite/releases/tag/1.92.1.7804-260318-088f9b3. The gitversion ones look like this: https://github.com/OoliteProject/oolite/releases/tag/1.93.1-181 or https://github.com/OoliteProject/oolite/releases/tag/1.93.1-improvePlistParsingMessages.1.

The main thing we want to be able to do is identify the commit which both the old and gitversion approaches enable. What gitversion offers is nicer looking version strings but only for CI releases at the expense of inconsistency with local/package build versions built off the same commit.

What I have proposed is an improvement over the old approach where the branch name is included in the version string giving the informational benefit that gitversion offers but without the complexity or inconsistency. What it does not have is gitversion's count that increments by 1 each time. I am not sure that count is worth the sacrifice of consistency and the increase in build complexity.

[oocube]

Please explain where inconsistency should arise.