Skip to content

Releasing

Releases are cut by pushing a git tag. The build computes the version from the tag, builds and tests everything, and publishes the packages to nuget.org. Nobody edits a version number in a project file.

How versions work

  • One version for all three packages. PackageGarden.Licensing (the validator), PackageGarden.LicenseGenerator.Core and PackageGarden.LicenseGenerator always get the same version, computed from one tag.
  • GitVersion computes it from tags and history, with the configuration in Automation/GitVersion.yml. This is the same setup as SEOChecker, pinned to GitVersion 5.10.x.
  • Release tags give exact versions. Tag v2.1.0 gives 2.1.0; tag v2.1.0-beta1 gives 2.1.0-beta1, with no generated suffix.
  • Other builds get a pre-release version and are never published:
  • main after a release: the next version with -r<n>, e.g. 2.1.1-r3;
  • pull requests: a pre-release named after the branch.
  • Local builds (without GitVersion) are 0.0.0-local.
  • The validator's assembly version stays 2.0.0.0, whatever the package version. Every Soeteman Software package was compiled against PackageGarden.Licensing, Version=2.0.0.0; changing it would stop them from loading the validator. Only the package, file (X.Y.Z.0) and product versions follow the tag.

Allowed tags

Form Example Package version
vX.Y.Z v2.1.0 2.1.0
vX.Y.Z-alphaN v2.1.0-alpha1 2.1.0-alpha1
vX.Y.Z-betaN v2.1.0-beta2 2.1.0-beta2
vX.Y.Z-rcN v2.1.0-rc1 2.1.0-rc1
  • N is one digit, from 1 to 9. NuGet compares beta10 as text and sorts it before beta9, so after beta9 move on to rc1. The order is alpha < beta < rc < stable.
  • Every version tag starts with v. A tag such as 2.1.0 (without v) is not allowed: GitVersion would count it as a version and shift every later version, so every build fails while such a tag exists.

Release a pre-release or a stable version

  1. Merge the pull request into main.
  2. Tag the commit the merge created on main (the merge or squash commit, never the commit on the pull request's branch) and push the tag:

    git fetch origin
    git tag v2.1.0-beta1 origin/main
    git push origin v2.1.0-beta1
    
  3. The build workflow runs for the tag:

  4. it checks the tag (see When a release build fails);
  5. it builds and tests everything, and packs the three packages;
  6. the publish job pushes them to nuget.org in this order: PackageGarden.Licensing, then PackageGarden.LicenseGenerator.Core, then PackageGarden.LicenseGenerator.

The run's summary shows the version and the published packages.

  1. PackageGarden.Licensing is listed on nuget.org. The two license manager packages are unlisted once all three are pushed: they don't appear in search, but install with an exact version:

    dotnet add package PackageGarden.LicenseGenerator --version 2.1.0-beta2
    

    If nuget.org refuses the unlist, the run still succeeds, shows a warning and lists the versions to unlist by hand in its summary (see Unlisting failed).

2.1.0-beta1 is incomplete

The v2.1.0-beta1 run pushed PackageGarden.Licensing and PackageGarden.LicenseGenerator.Core, then stopped when unlisting was refused, so PackageGarden.LicenseGenerator 2.1.0-beta1 does not exist. Use 2.1.0-beta2 or later.

A stable release works the same way with a tag such as v2.1.0.

Rules

  • Never move, delete or push again a tag that was published. nuget.org never accepts a version twice, and the build skips versions that already exist. A moved tag would publish nothing and nuget.org would keep the files of the original commit. Fix a mistake by tagging the next version.
  • One release tag per commit. With two release tags on one commit (for example v2.1.0-rc1 and v2.1.0), only the highest can be released. Tag them on different commits.
  • No patch releases of older version lines. A tag lower than an earlier release on main (for example v2.0.1 after v2.1.0) fails.
  • Only a tag push publishes. Pull requests, pushes to main and runs started by hand (even on a tag) never publish.

When a release build fails

Nothing is published when any check fails. The run's summary names the failed check.

Failed check What to do
Invalid form (e.g. v2.1, v2.1.0-bta1, v2.1.0-beta10) Delete the tag (below) and push a tag in one of the allowed forms.
Commit not on main The tag is on a commit that is not in main's history, usually the pull request's own commit. Delete the tag, merge the pull request first, then tag the commit the merge created on main.
Version differs from tag The computed version doesn't match the tag. Usually there is another, higher release tag on the same commit. Delete the lower tag and tag a different commit.
Build or tests failed Fix the problem in a pull request, delete the tag, and tag the merged fix.
Version tag without v Delete the tag that has no v (named in the message).
Automation/GitVersion.yml is missing Restore the file in a pull request. Without it, GitVersion would silently compute stable versions.
Publishing stopped part-way The summary names the package that failed and those already published. Re-run the failed publish job: published versions are skipped and it continues with the rest.
Unlisting failed (a warning, not a failure) All packages are published, but the versions under Unlist by hand in the summary are still listed. Open each link (nuget.org → Manage package → Listing), untick List in search results and save. To let the run unlist by itself, add NUGET_UNLIST_API_KEY (see One-time setup).

To delete a tag that was never published:

git push --delete origin v2.1.0-beta1
git tag --delete v2.1.0-beta1

Never delete a tag whose version is on nuget.org (see Rules).

One-time setup

Publishing uses NuGet trusted publishing: the publish job exchanges its GitHub identity for a key that only lasts for that run. No push key is stored in the repository or its secrets. It needs two settings, made once, in this order (a third is optional):

  1. GitHub: in the repository settings, under Environments, create (or open) the environment nuget. Set its deployment rule to tags matching v*, with no branch rules. Only release tag runs can then enter the environment, and so only they can request a key. GitHub creates the environment by itself, without rules, the first time a run uses it, so check the rule even if the environment already exists.
  2. nuget.org: signed in as rsoeteman (the owner of PackageGarden.Licensing), add a trusted publishing policy for GitHub Actions:
  3. owner Soeteman-Software, repository PackageGarden.Licensing;
  4. workflow file build.yml;
  5. environment nuget;
  6. allowed to create the package IDs PackageGarden.LicenseGenerator and PackageGarden.LicenseGenerator.Core, which don't exist on nuget.org yet.
  7. Optional, unlist key: the trusted-publishing key was refused (403) when the v2.1.0-beta1 run tried to unlist. To have the run unlist by itself, create a nuget.org API key (signed in as rsoeteman) with only the scope Unlist package and glob pattern PackageGarden.LicenseGenerator*, and add it as the secret NUGET_UNLIST_API_KEY of the environment nuget (not a repository secret, so only release tag runs can read it). nuget.org keys expire after at most 30 days; when it has expired, the run warns and you unlist by hand until you renew it. Without the key, the run tries the trusted-publishing key and otherwise asks you to unlist by hand.

The first release after this setup must be a pre-release. It proves that trusted publishing works for the private repository and that the new package IDs can be created. Only then tag the first stable version.

Notes

  • PackageGarden.LicenseGenerator.Core contains the validator assembly (PackageGarden.Licensing.dll) instead of depending on the PackageGarden.Licensing package, so nuget.org shows no link from the validator to the license manager. A site with the license manager and another package that depends on PackageGarden.Licensing gets the assembly twice; .NET keeps the newer file. The license manager is meant to run on its own site.
  • No package carries the umbraco-marketplace tag, so none is listed on the Umbraco Marketplace.
  • Out of scope: withdrawing a bad release (unlisting on nuget.org is a manual task for the package owner) and package signing (nuget.org adds its own repository signature).