ilkerhalil / Version.Net

msbuild package versioning configuration for our .Net projects

StirlingLabs/Version.Net

StirlingLabs.Version is an MsBuild package providing versioning configuration for our .NET projects.

_{Like a Version is a weekly live music segment on Triple J where musicians play one of their own songs plus a cover.}

What does it do?

It provides a predictable and deterministic date-based SemVer versioning scheme that Stirling Labs has standardised upon.

It uses SourceLink and GitInfo to add relevant versioning metadata to the artifacts created by dependent projects. The implementation of SourceLink also facilitates additional debugging capabilities in IDEs like Visual Studio, VSCode, and Rider. Dirty builds also have metadata to help identify their origin without exposing any private information.

How do I use it?

Note that when checking out a project that includes StirlingLabs.Version, you will need to get submodules;

# if the submodule isn't present in your clone
> git submodule update --init --recursive
# subsequently, when pulling from master also get submodules
> git pull --recurse-submodules

To create a new version, just create a new tag in "vYY.M.update" format. This can be done automatically for you;

> dotnet msbuild -t:CreateTag

If you have a solution with more than one project, you will get an error;

Microsoft (R) Build Engine version 16.9.0+57a23d249 for .NET
Copyright (C) Microsoft Corporation. All rights reserved.

MSBUILD : error MSB1011: Specify which project or solution file to use because this folder contains more than one project or solution file.

That's ok, you can just tell it to just use one of your projects in the solution.

> dotnet msbuild -t:CreateTag MyProject

or you can do it manually if you need the control;

> git tag -a v21.07.0 -m "My first version in July 2021"

...but please come up with a better message than that!

By default, the git push command doesn’t transfer tags to GitHub, so you will have to explicitly push tags after you have created them. This is just like sharing branches, we would push the tag we created above with;

> git push origin v21.07.0

How do I install it?

In this documentation, the solution level is assumed to be the directory of the solution (.sln) file, typically at the repository root. The project level refers to each of the the individual projects (.csproj) in the solution themselves.

This repo should be added as a submodule at the solution level. The command line operation is as follows;

> git submodule add -b master -- "[e-mail]:StirlingLabs/Version.Net.git" "StirlingLabs.Version"

The resulting .gitmodules should read as follows;

[submodule "StirlingLabs.Version"]
    path = StirlingLabs.Version
    url = [e-mail]:StirlingLabs/Version.Net.git
    branch = master

Also at the solution level, a Version.proj file should be created.

Content of Version.proj:

<Project>
    <PropertyGroup>
        <Authors>The Stirling Labs Team</Authors>
        <Owners>Stirling Labs</Owners>
        <Company>Stirling Labs</Company>
        <RepositoryType>git</RepositoryType>
        <RepositoryUrl>https://github.com/StirlingLabs/Utilities.Net.git</RepositoryUrl>
        <PackageProjectUrl>https://github.com/StirlingLabs/Utilities.Net</PackageProjectUrl>
        <GitDefaultBranch>main</GitDefaultBranch>
        <GitCommitsIgnoreMerges>true</GitCommitsIgnoreMerges>
    </PropertyGroup>
    <ImportGroup>
        <Import Project="StirlingLabs.Version/Version.proj" />
    </ImportGroup>
</Project>

At the project level, each project file should be edited to import the solution-level Version.proj by adding:

  <ImportGroup>
    <Import Project="../Version.proj" />
  </ImportGroup>

Note: we are assuming projects are in a subdirectory immediately below the solution (hence ../) as is best practice but adjust this as necessary.

For example, after editing, the StirlingLabsExampleProject.csproj file might look like this;

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        <TargetFramework>net5.0</TargetFramework>
        <Title>Stirling Labs Example Project</Title>
    </PropertyGroup>

    <ImportGroup>
        <Import Project="../Version.proj"/>
    </ImportGroup>
</Project>

Update GitHub Actions

Note that CI will need to be updated to check out submodules. In GitHub Actions, this means updating the checkout step:

    - uses: actions/checkout@v2
      with:
        submodules: 'true'