Release process

This project keeps release hygiene lightweight and explicit.

What is automated

  • release-drafter updates a rolling draft release on main.
  • GitHub release note categories are configured in .github/release.yml.
  • NuGet publication runs from .github/workflows/publish.yml when a GitHub Release is published.
  • Documentation site publication runs from .github/workflows/docs.yml:
    • PRs build docs and upload a site artifact for inspection.
    • main builds docs and deploys to GitHub Pages.

API docs generation policy

Generated DocFX API metadata (docs/api/*.yml) is not versioned.

  • API metadata is generated during doc builds from current source projects.
  • docs/api/ is ignored in git to avoid generated-file churn.
  • docs/_site/ is also generated output and is not versioned.

Before publishing a release

  1. Ensure CI is green on main.
  2. Confirm behavior changes are covered by tests.
  3. Ensure user-visible changes are clearly documented in PR descriptions.
  4. Add migration notes for any breaking or security-sensitive behavior.
  5. Verify docs and samples reflect the shipped API.
  6. Execute maintainer smoke checks on real Windows/macOS environments (see Manual validation).

Release notes guidance

Draft notes are grouped under practical headings:

  • Added
  • Changed
  • Fixed
  • Security
  • Docs / Maintenance

To improve draft quality, apply clear PR labels (feat, fix, security, docs, etc.). Use skip-release-notes (or release:skip) for PRs that should be omitted from user-facing notes.

Publish trigger

NuGet publication is explicit and GitHub-native:

  • publish a GitHub Release (not just a tag), or
  • run the publish workflow manually via workflow_dispatch.

The publish workflow restores, builds, tests, packs, and then pushes generated .nupkg files with --skip-duplicate. Symbol packages are not pushed by this workflow.

Docs trigger and inspection

Documentation workflow behavior:

  • On pull requests to main, docs build runs and uploads a docs-site artifact.
  • On push to main (or manual docs dispatch), docs build runs and deploys to GitHub Pages.

Maintainers can inspect the docs-site artifact to verify output before merge/release.

One-time setup

  1. Configure NuGet Trusted Publishing for the repository.
    • In nuget.org, create a Trusted Publisher for Sofiane-77/Thresh and scope it to .github/workflows/publish.yml.
    • Keep id-token: write permission enabled in the publish workflow.
    • Add repository variable NUGET_TRUSTED_PUBLISHER_PROFILE with the exact NuGet profile name used by NuGet/login@v1.
  2. Ensure repository maintainers use release labels on PRs to keep draft notes well categorized.
    • Recommended labels: feat, fix, security, docs, maintenance, dependencies, chore.
    • Optional exclusion labels: skip-release-notes or release:skip.
  3. Enable GitHub Pages in repository settings with GitHub Actions as the source.
  4. Keep GitHub Actions enabled for main and release events.

Versioning guidance

  • Follow SemVer intent.
  • Patch: fixes and non-breaking polish.
  • Minor: additive APIs and non-breaking improvements.
  • Major: breaking API or behavior shifts.

Release notes quality bar

Each release should state:

  • what changed,
  • why it changed,
  • whether there is a migration impact,
  • and any known limitations.