14. Release & Deployment
This page describes the maintainer release routine for CHD Studio. It is the same process the Release, CI and Docs workflows use, and it keeps the application bundles, GitHub release, GitHub Pages site and wiki in sync.
14.1 Versioning
The application version lives in two project files:
CHDStudio/CHDStudio.csproj-<AssemblyVersion>and<FileVersion>CHDStudio.Tests/CHDStudio.Tests.csproj-<AssemblyVersion>and<FileVersion>
All four values must match, and WhatsNew.md must contain a section whose heading starts with that exact version:
## 3.14.1 (2026-11-18)
scripts/ci/version.mjs validates all of this locally and in CI. A release tag is release_<version> and must match the project version exactly, for example release_3.14.1.
14.2 Build the six runtime bundles
The app is framework-dependent: it must never embed the .NET runtime. Publish with --self-contained false -p:PublishSingleFile=true so each output contains one single-file CHDStudio.exe/CHDStudio application plus the native Avalonia libraries and the matching bundled tools.
| RID | TFM | Bundle | Tools |
|---|---|---|---|
win-x64 | net11.0-windows | .zip | chdman.exe, 7za.exe |
win-arm64 | net11.0-windows | .zip | chdman_arm64.exe, 7za_arm64.exe |
linux-x64 | net11.0 | .tar.gz | 7zz, 7-Zip-License.txt |
linux-arm64 | net11.0 | .tar.gz | 7zz, 7-Zip-License.txt |
osx-x64 | net11.0 | .dmg | 7zz, 7-Zip-License.txt |
osx-arm64 | net11.0 | .dmg | 7zz, 7-Zip-License.txt |
Each bundle must be packaged on its native operating system: Windows zips on Windows, Linux .tar.gz on Linux (so tar stores the real Unix modes), and macOS .dmg with hdiutil on macOS. The Release workflow does this automatically with one matrix job per RID. For a local build, publish and package a RID with:
$version = "3.14.1"
$rid = "win-x64" # or linux-x64 / osx-arm64
$tfm = "net11.0-windows" # net11.0 for Linux/macOS
dotnet publish CHDStudio/CHDStudio.csproj `
-c Release `
-f $tfm `
-r $rid `
--self-contained false `
-p:PublishSingleFile=true `
-o "publish/$rid"
./scripts/ci/package-release.ps1 `
-Rid $rid `
-Version $version `
-PublishDir "publish/$rid" `
-OutputDir "dist"
package-release.ps1 creates exactly one architecture’s bundle, removes the other architecture’s tools and the unused .xml/.pdb files, and adds LICENSE.txt, ReadMe.md and WhatsNew.md. Linux and macOS bundles carry a single top-level CHDStudio/ folder; the Windows zip is flat. The two executables are set to 0755 and the data files to 0644 in the mode-preserving formats. The resulting names are:
release_<version>_win-x64.zip
release_<version>_win-arm64.zip
release_<version>_linux-x64.tar.gz
release_<version>_linux-arm64.tar.gz
release_<version>_osx-x64.dmg
release_<version>_osx-arm64.dmg
Copy the new bundles into CHDStudio/bin/Release/ without deleting anything that is already there. The release archive is append-only.
14.3 Verify before tagging
dotnet build CSharp_CHDStudio.sln -c Release
dotnet test CHDStudio.Tests/CHDStudio.Tests.csproj -c Release
node scripts/ci/version.mjs
jb inspectcode --output=InspectCode.log CSharp_CHDStudio.sln
The full suite must pass (1,314 tests: 1,285 unit + 29 integration), and InspectCode must report zero warnings and zero errors. The remaining InspectCode notes are suggestions, not release blockers. For a Linux bundle, extract the .tar.gz and confirm CHDStudio and 7zz are executable; for a macOS bundle, mount the .dmg and do the same. The release workflow repeats these checks. Confirm that each bundle contains LICENSE.txt, ReadMe.md, WhatsNew.md, the single-file application, the native libraries and only the matching tools. The .NET runtime must not be inside the executable.
14.4 Documentation, Pages and wiki
docs/ is the single source of truth for both documentation homes. Do not edit the GitHub wiki directly.
- Pages: Jekyll with the
just-the-docstheme. Every page has YAML front matter withtitleandnav_order; the theme renders the side menu. The color scheme is dark (docs/_config.yml). - Wiki:
scripts/ci/sync-wiki.mjscopiesdocs/*.mdto the wiki, convertingindex.mdtoHome.md, stripping Jekyll front matter and syncingdocs/_Sidebar.mdto the wiki side menu. WhatsNew.mdat the repository root is the release source. Keepdocs/WhatsNew.mdbyte-identical to it; the Docs workflow fails the build when the two differ.
The Docs workflow builds the site on pull requests and, on master, deploys Pages and pushes the wiki. The wiki push uses the WIKI_TOKEN repository secret; without it the step reports that it skipped the sync.
14.5 Tag and let CI publish
After the docs and version files are committed and pushed to master:
git tag release_3.14.1
git push origin release_3.14.1
The Release workflow then:
- validates the tag against the project version and
WhatsNew.md; - runs the test suite on Windows;
- publishes all six RIDs with the framework-dependent single-file settings;
- packages and verifies the six bundles (Windows
.zip, Linux.tar.gz, macOS.dmg) on their native runners; - creates a signed build-provenance attestation for each bundle;
- creates the GitHub release with the matching
WhatsNew.mdsection as its body; - verifies that all six bundle assets are attached.
Re-running the workflow refreshes the release notes and uploads the assets with --clobber. Verify a downloaded asset with:
gh attestation verify release_<version>_<rid>.<ext> --repo purelogiccode/CHDStudio
The Protect master ruleset requires a pull request and the CI, CodeQL, Docs and Dependency Review checks. Repository admins can bypass it for direct maintenance pushes; remove the bypass if every change must go through a PR. See Security & Quality for the full CI/security setup.
14.6 Update-check compatibility
The application checks https://api.github.com/repos/purelogiccode/CHDStudio/releases/latest, compares the release tag with its assembly version, and opens the release page when a newer version exists. Keep the tag format release_<version> and keep the asset names release_<version>_<rid>.<ext> (.zip, .tar.gz or .dmg); both are part of the release contract.
14.7 Post-release checks
- The GitHub release exists, is not marked prerelease, and has all six bundles.
- The release body is the new
WhatsNew.mdsection. - Each asset has a build-provenance attestation (
gh attestation verify). - The
CI,CodeQL,DocsandScorecardworkflows are green onmaster. - Pages shows the new version, dark side menu and the Security & Quality page.
- The wiki
Home,WhatsNew,_Sidebarand Security & Quality pages reflectdocs/. CHDStudio/bin/Release/contains the new six bundles and no older file was removed.- The application’s update check sees the new tag and offers it to older users.