BuildAndRelease

Build and release processes

Introduction

All the build and release tasks are implemented in code in tools/build as a C# project. The project uses Bullseye to implement a set of targets that support the build and release processes.
All targets are implemented as a static method in the BuildDefinition.cs file. A list of the available targets can be obtained by running the application without arguments:

dotnet run

This produces usage information as well as a list of all available targets. The targets will be described at the end of this document.

Important: the build project is intentionally decoupled from any CI tool to ensure that it is portable. This ensures that it is possible to move to a different CI service if needed, and also that anyone can run the process locally as well.

Current infrastructure

The source code is hosted on Github. The platform is also used enable collaboration through pull requests and issues.

A continuous integration is set-up on AppVeyor. The build is defined in appveyor.yml. The job simply sets-up a few environment variables then calls the build tasks described above. At the end, artifacts are published in case someone wants to download the binaries directly. Each commit on any branch triggers a build, although not every commit results in a new release.

NuGet.org is used to host packages of both pre-releases and stable releases.

Versioning

This project follows the SemVer guidelines. In practive this means that when the minor or patch versions are incremented, users should expect to be able to upgrade without any issues. When the major version is incremented, the users should expect to have to recompile and potentioally change their code.

YamlDotNet uses GitVersion to manage versions. GitVersion is configured in "Mainline" mode, which assumes that the master branch always contains releasable code.

GitVersion uses tags in the commit messages to control how the version number is incremented. All code that is merged on master should contain one of the following tags, depending on the type of change:

Type	Tag	Effect
Breaking change	+semver:breaking	Increments the major version number. Example
New feature (non-breaking)	+semver:feature	Increments the minor version number. Example
Bug fix (non-breaking)	+semver:fix	Increments the patch version number. Example

It is recommended that when merging any pull request, the appropriate tag is added to the commit message.

Releasing

The process of creating a release is driven by GitHub releases. Follow this procedure to create a release:

1. Run the Create a new release GitHub action to create a draft release. This generates release notes based on the list of commits since the previous release, and creates a draft release with those release notes. Make sure that all releant pull requests are referenced in the release notes.
2. Edit the release notes, then publish the draft release. This will trigger the continuous integration that will:
   • Determine the version number;
   • Build the code;
   • Publish a NuGet package;
   • Send a tweet about the release;
   • Add a comment to each pull request about the release.

Notes

• Before publishing the release, confirm that the version number makes sense according the content of the release. If it is incorrect, delete the release and add a new empty commit on master with the correct semver tag, then restart the release procedure.
• It may take a couple of minutes to show up in Nuget after the release is published