NuGet packages

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.*-*"/>

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:

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:

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

Example release-nuget.yml:

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:

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.*-*"/>

Add package sources

Nuget packages can come from many different places.

Where packages come from

1. GitHub Packages (Official-EwE): all internal Eii.* packages are published to and restored from https://nuget.pkg.github.com/Official-EwE/index.json.
2. Buf Schema Registry (BSR): BSR.* generated SDKs come from https://buf.build/gen/nuget/index.json.
3. nuget.org: all other public dependencies.

This is enforced via packageSourceMapping in NuGet.config:

1. Eii.* → github-Official-EwE
2. BSR.* → BSR
3. Everything else → nuget.org

The GitHub and BSR package sources are protected with secrets.

The NuGet.config file in the solution describes what package sources to use. It does not hold the secrets! So this file can be added to the Git repo.

To install the (PERSONAL) passwords encrypted on Windows you can use the following CLI command:

dotnet nuget add source "https://nuget.pkg.github.com/Official-EwE/index.json" -n "github-Official-EwE" -u "<your-github-username>" -p "<your-PAT>"

This changes the mother of all NuGet.config files which is stored in C:\Users\<user>\AppData\Roaming\NuGet. The secrets in this file are encrypted.