Skip to main content

Versioning Artifacts

Whenever a build produces artifacts, those should be identifiable with a unique version number. This avoids making wrong expectations about available features or fixed bugs, and allows for clear discussions between developers, QA team, and product users. The most common version approaches are are semantic versioning and calendar versioning.

Repository-based Versioning​

Fallout supports 4 different tools that help generating version numbers from your repository and its commits. Each of these tools comes with its own attribute that populates the field with the information calculated:

note

Please refer to the GitVersion documentation for any questions.

Tool Installation
# terminal-command
fallout :add-package GitVersion.Tool
Build.cs
[GitVersion]
readonly GitVersion GitVersion;

Target Print => _ => _
    .Executes(() =>
    {
        Log.Information("GitVersion = {Value}", GitVersion.MajorMinorPatch);
    });
note

Please refer to the Nerdbank.GitVersioning documentation for any questions.

Tool Installation
# terminal-command
fallout :add-package Nerdbank.GitVersioning
Build.cs
[NerdbankGitVersioning]
readonly NerdbankGitVersioning NerdbankVersioning;

Target Print => _ => _
    .Executes(() =>
    {
        Log.Information("NerdbankVersioning = {Value}", NerdbankVersioning.SimpleVersion);
    });
note

Please refer to the OctoVersion documentation for any questions.

Tool Installation
# terminal-command
fallout :add-package Octopus.OctoVersion.Tool
Build.cs
[OctoVersion]
readonly OctoVersionInfo OctoVersionInfo;

Target Print => _ => _
    .Executes(() =>
    {
        Log.Information("OctoVersionInfo = {Value}", OctoVersionInfo.MajorMinorPatch);
    });
note

Please refer to the MinVer documentation for any questions.

Tool Installation
# terminal-command
fallout :add-package minver-cli
Build.cs
[MinVer]
readonly MinVer MinVer;

Target Print => _ => _
    .Executes(() =>
    {
        Log.Information("MinVer = {Value}", MinVer.Version);
    });
info

Note that when the versioning tool fails to calculate version numbers, a warning will be logged and the attributed field remains uninitialized. In that case, you can try executing the issued command manually or fallout --verbosity verbose to reveal more detailed information. In most cases, the repository is either not initialized, has no commits, or is missing the tool-specific configuration file.

Dependency-based Versioning​

When your versioning is affected by external dependencies, Fallout provides another mechanism to load the latest version of those prior to build execution. Each attribute provides various properties to control which versions should be considered and how it should be transformed:

Build.cs
[LatestNuGetVersion(
    packageId: "JetBrains.ReSharper.SDK",
    IncludePrerelease = true)]
readonly NuGetVersion ReSharperVersion;

Target Print => _ => _
    .Executes(() =>
    {
        Log.Information("ReSharperVersion = {Value}", ReSharperVersion);
    });
Build.cs
[LatestGitHubRelease(
    identifier: "JetBrains/gradle-intellij-plugin",
    Pattern = @"v?(?<version>\d+\.\d+(?:\.\d+)?(?:\.\d+)?(?:-\w+)?)")] // default pattern
readonly string GradlePluginVersion;

Target Print => _ => _
    .Executes(() =>
    {
        Log.Information("GradlePluginVersion = {Value}", GradlePluginVersion);
    });
Build.cs
[LatestMyGetVersion(
    feed: "rd-snapshots",
    package: "rd-gen")]
readonly string RdGenVersion;

Target Print => _ => _
    .Executes(() =>
    {
        Log.Information("RdGenVersion = {Value}", RdGenVersion);
    });
Build.cs
[LatestMavenVersion(
    repository: "plugins.gradle.org/m2",
    groupId: "org.jetbrains.kotlin.jvm",
    artifactId: "org.jetbrains.kotlin.jvm.gradle.plugin")]
readonly string KotlinJvmVersion;

Target Print => _ => _
    .Executes(() =>
    {
        Log.Information("KotlinJvmVersion = {Value}", KotlinJvmVersion);
    });

You can learn more about different versioning aspects from the following resources: