2020/06/25

Continuous Versioning with Git and Gradle

Semantic Versaioning

Everybody knows semantic versioning. I think it's still good for software sold in boxes, regardless if the real paper ones or as downloads. But for continuous deployment it does not seem to be good enough.

Looking at the semantic version number does not tell you much. It is barely more than "hey, something was changed and the change is/maybe/should-not be disturbing". Not mentioning that the developers tend to forget to change the version number. And even when they do, it is unnecessarily  difficult to find what exact changes, i.e. commits, are in the semantically versioned release.

Continuous Versioning

Here comes what I call continuous versioning. It's more principle than exact versioning pattern, although I am going to suggest this one:

${semantic_version}-${commit_timestamp}-${commit_id}.

As you see the semantic version is still there, mainly because people like to see something familiar when you change things :). The main point is to add information about the last commit the change release contains.  The commit timestamp is there to give the version numbers nice chronological ordering. For developers is the most useful the last part - id of the commit, for which we use short hash of Git commit.

As you see there is no big demand for developers to increment the semantic version - it's nice if they do that, but each artifact still gets unique version number if they do not. What's even better, all the information can be gathered during build and used for various artifacts the build can produce - nowadays often executable package and Docker image.

The example how to achieve the described versioning with Gradle and use it to tag a Docker image artifact is below. To get information from Git we use both com.palantir.git-version Gradle plugin and Git command line, because the plugin does not provide timestamp info.

plugins {
    id 'com.palantir.git-version' version '0.12.3'
    id 'com.bmuschko.docker-remote-api' version '6.1.2'
}

def semanticVersion = '1.0.0'
def gitTimestamp = { ->
    def stdout = new ByteArrayOutputStream()
    exec {
        commandLine 'git', 'show', '-s', '--format=%ct', 'HEAD'
        standardOutput = stdout
    }
    return stdout.toString().trim()
}
def gitVersion = details.gitHash

version = semanticVersion + "-" + gitTimestamp() + "-" + gitVersion

// ...

import com.bmuschko.gradle.docker.tasks.image.DockerBuildImage


task buildDockerImage(type: DockerBuildImage) {
    // custom task to prepare files ind build/docker directory:
    // dependsOn  "prepareFilesForDockerBuild"
    inputDir = file('build/docker')
    images.add("mycooldockerrepo.com/${project.name}:${version}")
}

import com.bmuschko.gradle.docker.tasks.image.DockerPushImage

task pushDockerImage(type: DockerPushImage) {  
    dependsOn "buildDockerImage"

    images.add("mycooldockerrepo.com/${project.name}:${version}")
    
    registryCredentials {
       url = "mycooldockerrepo.com"
       username = System.getenv('docker_user') ?: "${docker_user}"
       password = System.getenv('docker_password') ?: "${docker_password}"
    } 
}

To package the version info inside the Docker image, we can define custom task prepareFilesForDockerBuild and uncomment the dependsOn line of buildDockerImage().
To save the version number into a file, e.g. named docker/version.txt, this should be inside that task:

new File("docker/version.txt").text = "${version}"

I hope this article helps somebody to look at versioning schemes from a newer point of view. I will add Maven version when I have one but my recent projects seem to be Gradle-only, so it coudl take time - feel free to post yours to share.