Skip to content

NuGet packages

Jump to bottom
Rikkert01 edited this page Oct 23, 2025 · 13 revisions

EII uses NuGet packages to share libraries. You can add a version to a library so people can develop within a stable context.

SemVer

Semantic Versioning (SemVer) is used for package versions: MAJOR.MINOR.PATCH

MAJOR version: when you make incompatible API changes MINOR version: when you add functionality in a backward-compatible way PATCH version: when you make backward-compatible bug fixes

(See also [semver.org](ook https://semver.org/), GitVersion docs, or Microsoft NuGet docs

So when you fix a bug or implement something without changing the interface, you only need to increase the PATCH version. This is basically the case for every PR that gets merged, except when the interface changes. In that case, the MINOR or even the MAJOR version should be increased. More about package dependency resolution at learn.microsoft.com/en-us/nuget/concepts/dependency-resolution

Wildcards

To avoid having to update the consuming packages with a new package reference (e.g., from 1.0.4 to 1.0.5), you can use a wildcard. Example:

<PackageReference Include="Your.Package.Name" Version="1.0.*-*"/>

image

Here, *-* means the latest PATCH version and any prerelease tags will be used. Examples of prerelease tags:

1.0.32-2 1.0.0-alpha

We probably don’t need to use prerelease tags for now. When the MINOR or MAJOR version changes, the PATCH (and MINOR in case of a higher MAJOR) resets to 0. (Gaps in version numbers are allowed.)

An example:

image

GitHub Actions

Building, packaging, and pushing packages can be automated using GitHub Actions. I’ve created two actions that can be called from any project: Eii.GithubActions Repository

  • ReleaseNuGetPackageNet48Net80

Uses windows-latest to create multi-target .NET Framework 4.8 / .NET 8.0 packages.

  • ReleaseNuGetPackageNet80

Uses ubuntu-latest and can only build .NET 8.0 binaries.

Example of a multi-target package:

image

The code to invoke the GitHub Action is located in the source repo, typically in a file like release-nuget.yml

image

Example release-nuget.yml:

image
  1. Trigger: push to master
  2. runs-on: platform (e.g., windows-latest for multi-target)
  3. Calls a generic GitHub Action

Version Bumping

o bump a MINOR or MAJOR version, the GitHub Action uses the GitVersion component: GitVersion You can include the following commands in your commit message:

+semver: major → increases MAJOR +semver: minor → increases MINOR +semver: patch → increases PATCH

If you only make backward-compatible changes, you only need to increase the PATCH version. No command is needed in the commit message for that. But if you want to bump the MINOR, include +semver: minor in your commit message. (This can be placed anywhere in the message.) Example:

image

This would result in the next version being something like 1.4.0. Note: You’ll need to update the consuming packages to:

<PackageReference Include="Eii.ValueChain.Storage" Version="1.4.*-*"/>

Clone this wiki locally