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.CoreandPackageGarden.LicenseGeneratoralways 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.0gives2.1.0; tagv2.1.0-beta1gives2.1.0-beta1, with no generated suffix. - Other builds get a pre-release version and are never published:
mainafter 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 againstPackageGarden.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 |
Nis one digit, from 1 to 9. NuGet comparesbeta10as text and sorts it beforebeta9, so afterbeta9move on torc1. The order isalpha<beta<rc< stable.- Every version tag starts with
v. A tag such as2.1.0(withoutv) 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¶
- Merge the pull request into
main. -
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 -
The
buildworkflow runs for the tag: - it checks the tag (see When a release build fails);
- it builds and tests everything, and packs the three packages;
- the
publishjob pushes them to nuget.org in this order:PackageGarden.Licensing, thenPackageGarden.LicenseGenerator.Core, thenPackageGarden.LicenseGenerator.
The run's summary shows the version and the published packages.
-
PackageGarden.Licensingis 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-beta2If 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-rc1andv2.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 examplev2.0.1afterv2.1.0) fails. - Only a tag push publishes. Pull requests, pushes to
mainand 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):
- GitHub: in the repository settings, under Environments, create (or open)
the environment
nuget. Set its deployment rule to tags matchingv*, 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. - nuget.org: signed in as
rsoeteman(the owner ofPackageGarden.Licensing), add a trusted publishing policy for GitHub Actions: - owner
Soeteman-Software, repositoryPackageGarden.Licensing; - workflow file
build.yml; - environment
nuget; - allowed to create the package IDs
PackageGarden.LicenseGeneratorandPackageGarden.LicenseGenerator.Core, which don't exist on nuget.org yet. - Optional, unlist key: the trusted-publishing key was refused (403) when the
v2.1.0-beta1run tried to unlist. To have the run unlist by itself, create a nuget.org API key (signed in asrsoeteman) with only the scope Unlist package and glob patternPackageGarden.LicenseGenerator*, and add it as the secretNUGET_UNLIST_API_KEYof the environmentnuget(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.Corecontains the validator assembly (PackageGarden.Licensing.dll) instead of depending on thePackageGarden.Licensingpackage, so nuget.org shows no link from the validator to the license manager. A site with the license manager and another package that depends onPackageGarden.Licensinggets the assembly twice; .NET keeps the newer file. The license manager is meant to run on its own site.- No package carries the
umbraco-marketplacetag, 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).