Skip to content

Release Process

This page documents the maintainer workflow for publishing ArchLinterNet preview/stable releases. The release pipeline is intentionally manual: a maintainer chooses the release scenario, reviews a dry-run, and only then publishes packages and creates the public release record.

Release records

A completed public release is recorded in three places:

  • NuGet.org packages — each generated .nupkg includes release notes and public package metadata.
  • GitHub Release — the GitHub Release body uses the generated release notes, and generated .nupkg / .snupkg files are attached as release assets.
  • GitHub Pages documentation — the MkDocs public product site is deployed when publication is enabled.
  • Workflow artifacts — every manual workflow run uploads generated release notes and package artifacts for review/audit of that run.

The GitHub Release is the durable human-facing release record. The workflow does not commit generated changelog files to the repository.

Versioning

ArchLinterNet follows Semantic Versioning 2.0.

Pre-1.0 preview releases use versions such as 0.1.0-preview.1. The manual release workflow calculates package versions from git tags based on the selected release scenario (preview, patch, minor, or major). Do not update Directory.Build.props just to run a release.

Version calculation rules

The workflow detects the latest SemVer-compatible git tag and calculates the next version:

Latest tag Release type Calculated version
v0.1.1-preview.2 preview 0.1.1-preview.3
v0.1.0 preview 0.1.1-preview.1
v0.1.1-preview.2 patch 0.1.1
v0.1.0 patch 0.1.1
v0.1.0 minor 0.2.0
v0.1.0 major 1.0.0

Tags use the v prefix. Package versions are emitted without v.

Version override

Use version_override only when automatic tag-based calculation cannot be used:

  • first release with no SemVer-compatible tags;
  • emergency recovery from a broken/manual versioning situation.

For normal preview continuation, leave version_override empty.

Public documentation boundary

GitHub Pages publishes only the public product documentation generated by MkDocs.

Internal project documentation remains in repository Markdown files and must not appear in the MkDocs navigation or generated site:

  • docs/internal/;
  • OpenSpec/change archives;
  • backlog governance;
  • issue-writing rules;
  • repository-agent instructions;
  • implementation planning notes.

The release workflow should deploy the generated MkDocs site only. It should not publish internal documentation as product docs.

Before publication, inspect package metadata and confirm:

  • PackageProjectUrl points to the public GitHub Pages documentation site;
  • RepositoryUrl points to the GitHub repository;
  • PackageReadmeFile is a concise user-facing README;
  • PackageLicenseExpression matches the repository license;
  • release notes are user-facing enough for NuGet.org;
  • no NuGet-facing link points to internal project documentation.

See NuGet package metadata for the canonical link model.

Workflow separation

Pull request CI and package publication are intentionally separate:

  • PR CI validates code and documentation.
  • The manual release workflow owns official package build, optional NuGet publication, GitHub Release creation, and GitHub Pages deployment.

PR CI must not call official release publication steps, request publishing identity tokens, push packages, create tags, create GitHub Releases, or deploy docs.

Local make pack is only for developer inspection. Official publication is performed by the manual GitHub Actions workflow.

NuGet.org trusted publishing setup

Before the first public publication:

  1. Configure a NuGet.org trusted publishing policy with these fields:
  2. package owner: eugene.malaschuk;
  3. repository owner: eugenemalaschuk-source;
  4. repository: arch-linter-net;
  5. workflow file: release-nuget.yml;
  6. environment: empty.
  7. Enable GitHub Pages for the repository and use GitHub Actions as the Pages source.

Classic long-lived NuGet API keys are not stored as repository secrets for this workflow. The release job uses GitHub's publishing identity flow to obtain the NuGet publish credential during the run.

NuGet.org is the package publication target for preview consumption. GitHub Packages is not used as package storage or as a mirror in the initial release pipeline.

Manual release procedure

Always run releases from the GitHub Actions UI. Do not publish official packages from a local machine.

Step 1: dry-run review

Run the release workflow with publish: false.

Expected dry-run result:

  • restore, Release build, and acceptance validation pass;
  • release notes are generated as workflow artifacts;
  • package artifacts are built with one calculated package version;
  • packages contain public metadata and package README;
  • nothing is pushed to NuGet.org;
  • no GitHub tag or GitHub Release is created;
  • docs are not deployed.

Before continuing, inspect:

  • release notes artifact;
  • package artifacts;
  • generated package metadata;
  • package README;
  • project/repository/license links.

Step 2: public publication

After dry-run artifacts are checked, rerun the workflow with the same release scenario and publish: true.

Expected public result:

  • packages are pushed to NuGet.org;
  • duplicate pushes are skipped for safer reruns;
  • GitHub tag and release are created from the workflow commit;
  • generated package assets are attached to the GitHub Release;
  • MkDocs product documentation is built and deployed to GitHub Pages.

After publication, verify:

  • NuGet.org shows expected package versions;
  • NuGet package project links open the public product docs;
  • NuGet repository links open the GitHub repository;
  • NuGet package README is product-facing;
  • GitHub Release exists and contains expected assets;
  • GitHub Pages deployment completed successfully;
  • internal docs are not visible in the published site navigation.

Record the published package IDs, version, GitHub Release URL, NuGet package URL, and GitHub Pages URL in the related issue or pull request notes.

Failure and rerun notes

  • If the dry-run fails, fix the underlying problem and rerun with publish: false.
  • If public publication fails before NuGet push completes, no GitHub Release should be created.
  • If NuGet publication partially succeeds, inspect NuGet.org and workflow logs before rerunning. The workflow should use duplicate-safe push behavior where possible.
  • If a GitHub Release already exists for the target tag, do not overwrite it blindly. Inspect the existing release and decide whether to fix the release manually or publish a new version.

Non-goals

The release workflow does not:

  • publish from pushed tags automatically;
  • publish docs independently from package publication;
  • publish internal project documentation as product docs;
  • commit generated changelog files;
  • maintain a custom changelog website;
  • publish packages to GitHub Packages.