Skip to content

Creating Tags and Releases

Jump to bottom
Paul den Boer edited this page Aug 13, 2025 · 36 revisions

Versioning Introducation

Semantic Versioning Basics

Most C# projects follow Semantic Versioning (SemVer): MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

  • MAJOR: Breaking changes
  • MINOR: New features, backward-compatible
  • PATCH: Bug fixes, backward-compatible
  • PRERELEASE: Optional tag like -rc, -beta, -alpha
  • BUILD: Optional metadata (e.g., commit hash)

Versioning Strategy Example

Stage Version Notes
Alpha 1.2.0-alpha.1 Early preview with incomplete features; used for internal testing and experimentation. Expect instability and frequent changes.
Beta 1.2.0-beta.1 Feature-complete but still undergoing significant testing. Suitable for external testers and early adopters. May contain known issues.
Release Candidate 1.2.0-rc.1 Versioning a project as a Release Candidate (RC) is an important step in signaling that your software is feature-complete and nearing final release, but still undergoing final testing.
Final Release 1.2.0 Stable, production-ready version. All major bugs resolved and thoroughly tested. This is the version recommended for general use.

NuGet Considerations

Pre-release versions (like -rc.1) are not installed by default unless explicitly requested. Use dotnet pack to generate the .nupkg with the correct version. Consumers must specify --prerelease when installing via CLI.

What Are VersionPrefix and VersionSuffix?

These two properties combine to form the full Version used by NuGet and other tools:

<PropertyGroup>
  <VersionPrefix>1.2.0</VersionPrefix>
  <VersionSuffix>rc.1</VersionSuffix>
</PropertyGroup>

This results in:

Version = 1.2.0-rc.1

Updating Version and Releasing

Before You Start

  • Before you start, ensure all PR's are merged to the current development branch (develop-2.0 at the time of writing this page)
  • Capture the Firely .NET SDK version used in the VONK CQL Plugin. These need to be in sync. See property FhirNetApiVersion in Vonk.props
  • You will need permissions to create Tags and Releases

Update Version

To update the version in the .NET assemblies follow these steps. Refer to this example PR 852 which upgrades to 2.1.0-beta.1. (Note that before this, the versioning was done incorrectly on the alpha releases)

  1. Start by creating an issue on the backlog.

  2. Check out the latest repo and create a branch

  3. Open all the *.props files, and update the VersionPrefix and VersionSuffix properties e.g.

    <PropertyGroup>
  <VersionPrefix>1.2.0</VersionPrefix>
  <VersionSuffix>rc.1</VersionSuffix>
</PropertyGroup>

  4. Important - Keep the version in sync between the Firely .NET SDK used in the VONK CQL Plugin and the CQL SDK. Copy the FhirNetApiVersion in the VONK repo, Vonk.props and update FirelySdkVersion in cql-base.props and cql-demo.props.

  5. Commit the branch and pull and merge it. Important: You cannot deploy Releases from a Pull Request itself.

Tagging

Before creating a Release, you have to first create a Tag.

The next step is to tag a commit with a version number. After completing the steps above, continue as follows:

  1. Find the commit version that you want the new release on.

  2. On your local environment open a command prompt in your folder containing the repo, then run these commands (replace the {tags}):

    1. Optional: To check the current list of tags in the repo
    git tag --list
    1. Make sure you're on the main branch or your repo with the latest commit. Then capture the commit ID for the next step
    git rev-parse HEAD
    1. Create a new tag for a specific commit id, and with an optional message. In our case, just make it the same as the version
    git tag -a v{version} {commit-id}  -m "{version}"
    1. Push the new tag to the remote repo. You will need permissions for this.
    git push origin v{version}

Releasing

Note: For the CQL repo, there is no Release Notes.md in the repo yet. Instead, this can be added at the step where the Release is created mentioned later on this page.

After pushing the new tag from above, manually create a release for it:

  1. In GitHub, go to Tags, click ... on the tag you're interested to release and click Create Release

  2. Click the Generate Release Notes button, and add additional comments as necessary

    1. For pre-releases (alpha, beta, release candidates), tick the checkbox for Pre-release

    2. For final releases that should become the latest release shown on the repo homepage, tick the checkbox for Latest Release

  3. Wait for pipeline to build

  4. Click Approve on the last Deploy packages to Nuget step

  5. A few minutes may pass before the Nuget package is visible.

Nuget Packages

image

References

  • Creating Releases for firely-net-sdk, which is a useful guide to a more complete process, and includes steps for adding manual release notes.

Quick Links

Clone this wiki locally