Release Process

This page describes how versions are managed and how builds, releases, and documentation are published by the project's GitHub Actions pipelines.

Versioning

The application uses three-part versions such as 1.5.0:

Location	Purpose
`RetroGameCoverDownloader/RetroGameCoverDownloader.csproj` → `AssemblyVersion`, `FileVersion`	Application version, checked by the release pipeline
`RetroGameCoverDownloader.Tests/RetroGameCoverDownloader.Tests.csproj` → `AssemblyVersion`, `FileVersion`	Kept in lockstep with the application
`WhatsNew.md`	User-facing release notes for the upcoming version
Git tag `release_<version>`	Triggers the release pipeline and names the GitHub release

Continuous integration

.github/workflows/ci.yml runs on every push to master, every pull request, and on demand:

Checkout and .NET 10 SDK setup (with NuGet cache).
dotnet restore and dotnet build -c Release.
dotnet test -c Release — the full unit test suite. Test results are uploaded as an artifact.

Release pipeline

.github/workflows/release.yml is triggered by pushing a tag such as release_1.5.0, or manually with a version input. It runs four jobs:

Job	What it does
version	Resolves the version from the tag or input and validates the `X.Y.Z` format
verify	Fails if `AssemblyVersion` does not match the requested version, then builds and tests the solution
bundles	Runs `scripts/package-release.ps1 -SkipTests` to publish the framework-dependent single-file executable for `win-x64` and `win-arm64`, zips each with the documentation, writes SHA256 checksums to the run summary, and uploads the `release-bundles` artifact
publish	Waits for approval in the protected `release` environment, downloads the reviewed bundles, verifies both zips are present, and creates or updates the GitHub release with `WhatsNew.md` as the release notes

Bundle contents

Each release_<version>_win-<arch>.zip contains:

RetroGameCoverDownloader.exe (framework-dependent single-file publish)
ReadMe.md
LICENSE.txt
WhatsNew.md

Packaging locally

The same script used by CI can be run from a developer machine:

# Run tests, publish both architectures, and write the zips
.\scripts\package-release.ps1 -Version 1.5.0

# Skip tests (CI runs them in a separate job) and stage elsewhere
.\scripts\package-release.ps1 -Version 1.5.0 -SkipTests -StagingDirectory C:\Temp\rgcd-staging

Bundles are written to RetroGameCoverDownloader\bin\Release by default, and the script prints the SHA256 hash of each zip.

Required repository configuration

Setting	Where	Purpose
`release` environment with required reviewers	Settings → Environments	Approval gate before the release is published
Workflow permissions	Repository default settings	The workflow uses `contents: write` only in the publish job
Pages source: GitHub Actions	Settings → Pages	Allows the docs workflow to deploy the site
Wikis enabled + an initial page	Settings → Features → Wikis	The wiki repository must exist before it can be cloned by CI
`WIKI_TOKEN` secret	Settings → Secrets and variables → Actions	Classic PAT with `repo` scope, used to push documentation to the wiki; without it the wiki job is skipped

Documentation pipeline

.github/workflows/docs.yml runs when documentation changes are pushed to master (and on demand):

Builds the DocFX site from docs/docfx.json.
Deploys the generated site to GitHub Pages at https://purelogiccode.github.io/RetroGameCoverDownloader/ using the official Pages actions.
Syncs the Markdown sources to the GitHub Wiki with scripts/publish-wiki.ps1:
- index.md is published as Home.md.
- Pages are flattened into the wiki root and .md links are converted to wiki-style links.
- _Sidebar.md is generated from docs/guide/toc.yml, giving every wiki page a lateral menu.
- Pages are added or updated; unrelated wiki pages are left untouched.

Cutting a release

Update WhatsNew.md with the user-facing changes.
Bump AssemblyVersion and FileVersion in both .csproj files to the new version.
Commit and push to master; make sure CI is green.
Push the tag:
```
git tag release_1.5.0
git push origin release_1.5.0
```
Alternatively, run the Release workflow manually and provide the version.
Review the bundles job summary (sizes and SHA256 hashes) and approve the release environment to publish.
Verify the release page and the updated documentation links.

Maintenance notes

Keep WhatsNew.md accurate for the next version; it becomes the public release description.
The release pipeline accepts only three-part versions; pre-release suffixes are not supported.
The verify job fails early when the tag and the project version differ, preventing mislabeled bundles.
Documentation is versionless by design — it always describes the current master state.

Table of Contents