Change versioning scheme to git

[msteiger]

Currently, we're using Jenkins build numbers (plus job name) to version different builds. An example:

 2.0.0-0.113+TerasologyLauncherNightly

I see two problems with that: Jenkins build number are not reliable (local builds, server unavailable, job count reset, etc) and it's not possible to match them with git commits. For those cases, the current datetime is used.

Instead, I propose to use git describe to version builds. It is available wherever git is available and does not require Jenkins (Jenkins knows which commit it uses for building, so that link is left intact). It looks like this:

v1.4.2-121-gda71b2e

It starts with the last tagged commit (v1.4.2), followed by the number of commits since then(121) which gives an order (for comparison and sorting) and ends with the current commit. It works nicely for server and local builds. CrashReporter and WorldViewer already use this system in practice. It's also easy to realize: just run git describe on the command line.

--- Want to back this issue? **[Post a bounty on it!](https://www.bountysource.com/issues/5528267-change-versioning-scheme-to-git?utm_campaign=plugin&utm_content=tracker%2F715506&utm_medium=issues&utm_source=github)** We accept bounties via [Bountysource](https://www.bountysource.com/?utm_campaign=plugin&utm_content=tracker%2F715506&utm_medium=issues&utm_source=github).

[skaldarnar]

How exactly are nightly and stable builds distinguished with this method?

[msteiger]

The version is always relative to the last stable build. For stable builds, the version looks like this:

v2.0.0

No relative info, no commit SHA, just the plain version. For nightly and local builds they are added to let you know what and how much has changed since the last stable build.

[mkalb]

The current implementation is based on Jenkins builds. It was (and is?) the only official build server. The launcher uses the jenkins build number to recognize new versions for launcher and game.

The version objects also contains the git commit and other useful informations:

buildNumber=11
buildId=2014-10-11_10-55-20
buildTag=jenkins-TerasologyLauncherStable-11
buildUrl=http\://jenkins.terasology.org/job/TerasologyLauncherStable/11/
jobName=TerasologyLauncherStable
gitBranch=master
gitCommit=cc4c630e8ecc4535afb353892fa56c97b550d38f
dateTime=2014-10-11T14\:55\:28Z
displayVersion=1.4.2

[Cervator]

Interesting idea :-)

I've been vaguely aware of Git tags but like sub-modules haven't spent enough time understanding them. Mainly I've noticed from doing a release on GitHub also coming with a tag. Which would seem to work well with this since you can also release on GitHub with an existing tag.

I need to think about how that might interact with the idea of develop/master branch jobs in Jenkins and releases there for engine + modules, probably better than what I had in mind.

Although one oddity. Currently I see the tags I created for engine in my local workspace, but git describe doesn't show the latest tag, but an ancient one @begla added years ago:

C:\Dev\Terasology\Git\integrate\Terasology>git tag
0.12a
0.1a
highlight23
stable29
stable30
stable31
stable32
stable37
stable38
stable39
stable41
stable42
untagged-4b29ff9040aad554a2b6
untagged-9f0b44a85a06aea32eab

C:\Dev\Terasology\Git\integrate\Terasology>git describe
0.12a-3723-gc44e230

From what I can gather from Git doc it sounds like maybe the ancient tags are annotated while the ones created via GitHub releases are light-weight tags. Resulting in git describe thinking the last proper tag is 3723 commits ago.

I figure this will work OK with SemVer, since the number of commits since last tag (which by convention should be a release) will allow pre-release/snapshot builds to sort correctly, even ignoring the commit hash. Although I think the plain format from git describe technically clashes with the convention

git describe yields the following: v1.4.2-121-gda71b2e SemVer convention would expect: v1.4.2-121.gda71b2e

Only one - allowed with . serving as the separator and + to add optional build metadata

That's a pretty minor tweak we could probably fix just in case we use any tools that adhere exactly to SemVer

http://semver.org/

Also we might get odd sequence issues with local builds or unusual branch builds, another minor issue. In theory two feature branches both 3 commits ahead of the last tag would make similar versions:

v1.4.2-3-ab3de51d
v1.4.2-3-b3c5d2fc

Not that we'd necessarily be any better off with the current setup. We could also inject the branch name into custom branch builds to make parallel branch builds clearer. Not that we are likely to encounter that scenario.

Just trying to be thorough! :D

[skaldarnar]

Apologies for merging the associated PR (#295) already! I did not realized that I was looking at this issue in the state of last night... sorry! Should we revert the changes until we figured this completely out?

[msteiger]

@mkalb I want to keep it that way. Only two minor changes: I'd like to move the info file from output to src/resources to be able to use it in the IDE and let git describe create the displayVersion entry.

@Cervator: yes, the tags were not annotated :cry: I fixed it manually for the latest launcher version tag #290. While annotated tags are preferred, git describe --tags also considers lightweight tags.

According to semver, the hyphen denotes a pre-release which it isn't - it's commits since the release.

1. We could stick with the + ? This would make it build metadata and therefore irrelevant for sorting though (see semver at no. 10).
2. We could use the commit counter as semver patch number and use the commit as build metadata - e.g. 2.0.42+b3c5d2fc. This would ensure version precedence.

Gradle does not explicitly state how it compares two version. I tend for option 2 - just to be safe.

http://www.gradle.org/docs/current/userguide/dependency_management.html

[Cervator]

Yeah I wasn't sure about the pre-release qualifier but figured it could still be used. I like the idea of commit count as patch, but I think that might get tricky? If you rebuild in Jenkins for any reason you'll get the exact same version id? While now we've got the snapshot # based on the build # in Jenkins. Or do we just add that in?

2.0.42-b3c5d2fc+123

or

2.0.42+b3c5d2fc.123

With 123 being the build job id from Jenkins, only if built from Jenkins

Patch number could also jump quite a bit that way, if a PR gets merged with 20 commits in it the patch number would go up by 20? Definition states patch number indicates backwards-compatible change like bug fixes, while it could end up just being readme changes or checkstyle fixes. More nitpicks that may not matter :-)

I do like the idea of not worrying about tracking patch number in a config file. Major/minor change less frequently so that's fine. Yay fewer dummy commits

[msteiger]

Let's assume that Jenkins builds the same code (same commit) twice. Do we want to see that in the version or should they look identical? Personally, I'd like to add the Jenkins build number as metadata, just as @Cervator suggested. The semver-compliant version would be:

2.0.42+b3c5d2fc.123

Patch number would go up by 20 if PR gets merged, yes. This also allows you to build jars with only some of the commits from the PR.

[Cervator]

Sounds good to me. Nerdily exciting!

Anybody else want to weigh in? @immortius ?

[immortius]

I'm not fussed with the versioning of snapshot/nightly builds, so I'm happy with this suggestion.

[Cervator]

Bit of an addendum: https://github.com/ajoberstar/gradle-git now has more release management support. Might be worth a closer look too :-)