versionName

versionName is a tiny Java library that allows for conveniently reading the version name of an application from

• Manifest,
• property file or
• from a constant generated by an annotation processor.

Reading from manifest or property file

versionName consists of one class (as said before it's tiny) VersionNames that provides methods for reading the version name. The public methods return a String that is never null. In case of error, messages are written to a SLF4J-logger.

• VersionNames.getVersionNameFromProperties(),
• VersionNames.getVersionNameFromManifest()

To use versionName, either copy VersionNames to your classpath or add the latest stable version to the dependency management tool of your choice.

Read more about it in those two blog posts (Note that this refers to version 1.x and the maven coords and package names have changed since!)

• Version names with Maven: Creating the version name (which refers to the examples) and
• Version names with Maven: Reading the version name (which refers to the library itself).

With maven for example

<dependency>
    <groupId>com.cloudogu.versionName</groupId>
    <artifactId>versionName</artifactId>
    <version>2.0.0</version>
</dependency>

You can also get snapshot versions from our snapshot repository (for the most recent commit on develop branch). To do so, add the following repo to your pom.xml or settings.xml:

<repository>
    <id>snapshots-repo</id>
    <url>https://oss.sonatype.org/content/repositories/snapshots</url>
    <releases><enabled>false</enabled></releases>
    <snapshots><enabled>true</enabled></snapshots>
</repository>

Alternative: Using the annotation processor

From a runtime perspective, its actually a bit odd reading a build-time constant from a file where it could just be "baked into" the application source code.

This misery can be ended using the VersionNameProcessor. It generates a constant Version.NAME (package, class and field name can be customized). With this mechanism there is not even the need for the com.cloudogu.versionName:versionName dependency.

In order to trigger the process, an annotation @VersioName must be set on a class or package. The Version class is then generated into the same package when the following dependency is added to the build (e.g. with maven):

<dependency>
    <groupId>com.cloudogu.versionName</groupId>
    <artifactId>processor</artifactId>
    <version>2.1.0</version>
    <!-- This dependency is only needed during compile time and should not be packaged into final JAR -->
    <scope>provided</scope>
</dependency>

Using the provided scope will add zero dependencies to your project, only the generated class.

In addition, the version name to be written must be passed as an argument versionName to the compiler, e.g. like so using maven:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.8.0</version>
    <configuration>
        <compilerArgs>
            <arg>-AversionName=${versionName}</arg>
        </compilerArgs>
    </configuration>
</plugin>

See also

• the full example using the annotation processor and
• the unit tests of the annotation processor.

Examples

The examples show how to write a version name to your application using maven and how it can be read using the library from within applications (JAR or WAR). See examples/README.md

Jenkins

Running Jenkinsfile with the pipeline plugin (tested with version 2.4) requires

• Docker
• Optional: You can add a build parameter RECIPIENTS that contains a comma-separated list of all email recipients

Releasing

• rebase main onto develop
• mvn versions:set -DnewVersion=2.2.0 -DgenerateBackupPoms=false
• git commit -m 'Prepare release', tag -s, push
• rebase develop onto main
• mvn versions:set -DnewVersion=2.2.1-SNAPSHOT -DgenerateBackupPoms=false
• git commit -m 'Prepare next development iteration', push

We might get rid of develop branch and the rebasing in the future.