Release Checklist

Adopted: 2026-10-26 Release timing: v1.6.0 is the current release; unified Windows/Linux/macOS x64/arm64 bundles are built from the same gates used for v1.0.0, v1.1.0, and v1.2.x. Release definition: v1.0 is a documented-compatibility release, not a full-compatibility one. v1.1.0 was a maintenance update; v1.2.0 added features, accuracy telemetry, and broader disc support; v1.2.1 added arm64 bundles; v1.2.2 added interpreter/high-res/rewind performance, the opt-in managed JIT, library health and database work, memory capacity options, and eight PBUS ports; v1.3.0 adds 480i/240p detection, deinterlacing, and field blending; v1.4.0 adds online cover art, latency controls, unsigned-disc support, and the exact NTSC field clock; v1.5.0 adds GPU HQx, the 24-bit VDL background, reference field-boundary timing, and CD parity. v1.6.0 completes the 378-title compatibility matrix, tightens CD poll/speed/session behavior, and hardens settings/NVRAM persistence. Ship the platforms and titles that are validated, publish an honest per-title matrix and known issues, and move everything else to the post-1.0 backlog.

This checklist is the release gate. A checked box must have evidence (a command, CI run, screenshot, or recorded hash), not just an intention. Update docs/Status.md, docs/Compatibility.md, docs/KnownIssues.md, and CHANGELOG.md as items complete.

1.1.0 maintenance gate

1.3.0 field-handling gate

1.4.0 feature and accuracy gate

1.5.0 accuracy and GPU-HQx gate

1.6.0 compatibility-completion gate

Cover-art hosting gate

Run packaging/package-covers.ps1; review artifacts/covers/v1/report.json.
Confirm every catalog image reloads and hashes correctly, and every game ID is mapped at most once (the packager verifies this automatically).
Upload artifacts/covers/v1 with packaging/publish-covers.ps1; verify https://assets.purelogiccode.com/5do/v1/catalog.json returns the expected packVersion and cover count.
Test a clean cache on Windows and Linux: catalog refresh, on-demand download, bulk-pack download, covers verify, and offline fallback to cached/local covers.
Confirm the catalog and images are not inside any release bundle.
Confirm the rights/takedown notice is present in docs/CoverArt.md and linked from Settings > Covers.

1.2.2 performance and library gate

1.2.1 arm64 packaging gate

Bump FiveDoVersion.Version and Directory.Build.props to 1.2.1.
Add win-arm64, linux-arm64, and osx-arm64 to the bundle script and CI matrix.
Verify PE ARM64, ELF aarch64, and Mach-O arm64 apphosts.
Full suite 1,597/1,597 passes; format and inspectcode are clean.
Build all six bundles and keep local copies in src/FiveDo.Frontend.Avalonia/bin/Release.
Create and push tag v1.2.1; the release workflow published six versioned bundles and checksums: https://github.com/purelogiccode/5DO/releases/tag/v1.2.1. CI run https://github.com/purelogiccode/5DO/actions/runs/41583317988 passed all six bundle jobs and the publish job; all six SHA256SUMS.txt entries verify.

1.2.0 feature gate

Bump FiveDoVersion.Version and Directory.Build.props to 1.2.0.
Update CHANGELOG.md, docs/WhatsNew.md, docs/ReleaseNotes-1.2.0.md, README.md, docs/Status.md, and docs/index.md.
Verify the Direct3D 11 backend, startup release checks, fuzz harness, per-edge overscan/void border, screenshot gallery, refresh-rate setting, flat CHD/raw ISO support, and FIQ/DMA/DSP audit changes are documented.
Full suite 1,597/1,597 passes; dotnet format --verify-no-changes is clean.
jb inspectcode --severity=WARNING reports 0 results before producing bundles.
Build the Windows, Linux, and macOS x64 bundles.
Windows/Linux bundle CLI selftest and desktop --smoke-test pass; the macOS bundle is validated as Mach-O x86_64. CI run https://github.com/purelogiccode/5DO/actions/runs/41581528432 passed all three bundle jobs and the publish job.
Keep local bundle copies under src/FiveDo.Frontend.Avalonia/bin/Release.
Create and push tag v1.2.0; the release workflow published the bundles, checksums, and release notes: https://github.com/purelogiccode/5DO/releases/tag/v1.2.0. All three SHA256SUMS.txt entries verify.

0. Recommended v1 scope

These are recommendations; the release owner confirms or changes them in section 1. The important rule is: do not claim a platform or a playable title that has not been validated.

Item	Recommended v1 scope	Notes
Validated desktop platform	Windows x64	WGL and ANGLE/GLES validated; CPU fallback works
Secondary desktop builds	Linux x64 (full suite and CLI/frontend smoke passed; GL preview); macOS x64/arm64 built and architecture-validated	Linux GPU presentation is unvalidated under llvmpipe; Windows GL remains the validated renderer
Desktop arm64	Built and architecture-validated; runtime validation post-1.0	GLES 3.1, Tier B timing, and DPI are unvalidated; Raspberry Pi is out of scope
Compatibility set	414 unique titles / 378 game-test-set titles; 375 playable under the binary beyond-title rule	Per-title status must stay honest and evidenced
Disc formats	ISO, BIN, CUE+BIN, CHD	Already implemented and tested
Renderer	OpenGL default, CPU fallback	Filter family is complete
Packages	One bundle per system and architecture	`5do-<version>-win-x64.zip`, `5do-<version>-win-arm64.zip`, `5do-<version>-linux-x64.tar.gz`, `5do-<version>-linux-arm64.tar.gz`, `5do-<version>-osx-x64.tar.gz`, `5do-<version>-osx-arm64.tar.gz`; each contains the CLI, desktop app, README/license/notices/whatsnew. The .NET 10 runtime is a host prerequisite and is not bundled
Distribution model	Donationware	Non-commercial, source-available; voluntary donations only, no sales
Version	`v1.6.0`	Bump `FiveDoVersion.Version` and `Directory.Build.props`; v1.0.0, v1.1.0, v1.2.0, v1.2.1, v1.2.2, v1.3.0, v1.4.0, v1.5.0, and rc.1 are historical
Release timing	Prepared 2026-11-08	v1.6.0 bundles and checksums are attached to the GitHub release

1. Scope and decisions

Confirm supported RIDs and which one is the validated target: Windows x64 is the validated target for 1.0.0; Linux x64 full suite and CLI/frontend smoke passed and GPU presentation is preview/best-effort. The other RIDs are build artifacts only unless separately smoke-tested.
Confirm the supported title list and each title's status: Playable, Boots/menus, or Known issues (12 documented titles; five showcase titles with scripted gameplay evidence).
Confirm the release version: 1.0.0; legal/distribution sign-off is recorded.
Confirm the distribution model and license in docs/Licensing.md: FreeDO modified GNU LGPL, donationware (non-commercial/source-available; voluntary donations, no sales), recorded in the root LICENSE.
Confirm installers/signing/notarization are out of scope for 1.0.0.
Record the decisions in this file and in docs/Status.md.

Recommended title statuses:

Title	v1 status to document
Wolfenstein 3D	Playable: fresh game, movement/fire, save/load; known long load
Lemmings	Playable: passcode path, gameplay start, save/load
Road Rash	Playable race, not full-race completion; document the known wreck/end state
Alone in the Dark	Playable room/menu/intro; inventory not scripted
Space Ace	Playable interactive scene start; longer decisions unvalidated
Gex	Boots/attract scene; input not scripted
Need for Speed	Boots/menus; input not scripted
Super Street Fighter II Turbo	Boots/attract match; input not scripted
Total Eclipse	Boots/attract gameplay; input not scripted
Killing Time	Boots/title menu; input not scripted
Theme Park	Boots/title menu; captured menu audio is silent
Return Fire	Boots/menu; input not scripted

2. Legal and attribution (hard gate)

Distribution/license decision recorded in docs/Licensing.md and the root LICENSE.
THIRD-PARTY-NOTICES.md covers FreeDO/4DO, Opera/libopera, CHDSharp, Avalonia, Silk.NET, Serilog and its console/file sinks, the bundled OpenAL Soft 1.23.1 runtime, and other NuGet dependencies. See ReleaseLegalReview.md.
OpenAL Soft LGPL-2.0-or-later obligations (notice, corresponding source offer, relinking rights) are included in the release decision. The runtime is bundled in the Windows/Linux/macOS x64 bundles. Evidence: docs/OpenALSoft.md records the notice, the exact upstream 1.23.1 source, the three-year written source offer, and relinking instructions; docs/OpenAL-Soft-COPYING.txt contains the complete LGPL-2.0 text; packaging/package-bundle.ps1 copies both into every bundle, and the win-x64 bundle was inspected after packaging.
About dialog and CLI --version/license output are current.
No BIOS ROM, disc image, extracted asset, WAV capture, or copyrighted game content is tracked in the repository; packaging uses only publish output plus README/notices/licensing.
Release owner/legal sign-off recorded in section 6: project owner approved distribution under the FreeDO modified GNU LGPL as free, open-source donationware (non-commercial; voluntary donations only), 2026-11-02.

This is the only item that can block the release independently of engineering. Start it first. The engineering audit and the remaining owner/legal decisions are recorded in ReleaseLegalReview.md.

3. Build, test, and CI

Suggested commands:

dotnet build 5DO.sln -c Release
dotnet test tests/FiveDo.Tests/FiveDo.Tests.csproj -c Release
dotnet format 5DO.sln --verify-no-changes
jb inspectcode 5DO.sln --sEverity=WARNING --no-build
dotnet run -c Release --project benchmarks/FiveDo.Benchmarks -- --frames 600 --gate

4. Stability and compatibility

Run a 10-minute soak (36,000 frames at 60 Hz) on each showcase title, and at least a boot/menu soak on the remaining supported titles. Record final PC and frame hash; compare against docs/TestCorpus.md where a baseline exists.

Use tools/release-soak.ps1 for the per-machine run. The corpus differs between the two development machines, so a Missing on this machine row is expected and is not a failure. The script uses archived 12k states for absent discs when available and writes summary.md/summary.json for the release evidence.

4.1 Full-collection compatibility sweep (M13)

The v1.0 release uses the full local collection's recorded loadability status; the post-1.0 visual review continues from it. See CompatibilitySweep.md and GameCompatibilityList.md.

Run the 3,000-frame loadability sweep over J:\Panasonic 3DO (589 CHDs) and G:\MAME\MAME Software List CHDs\3do (5 CHDs): 594 tested, 593 render, 1 known boot failure (Crash 'n Burn Japan), 0 not loadable.
Every image has a loadability status and an evidence path.
Every Not Loadable result has a triage note and reproduction command (none remain).
Rendered titles have a screenshot and a short input smoke test (post-1.0 visual review).
The high-resolution pass has a per-title result (post-1.0).
Linux x64 build/test/smoke results are recorded (2026-11-02): the full test suite 1,473/1,473, CLI selftest/bench/info, a 3,000-frame Wolfenstein boot, non-silent audio, and the frontend --smoke-test passed on Linux Mint 22.3. The GL probe timed out under llvmpipe, so GPU presentation is preview/best-effort.

M13.5/M13.6 (in-game/visual and high-resolution review) are post-1.0 and do not block v1.0. Linux x64 full suite and CLI/frontend smoke passed; the unified bundles are built and published by CI. Linux GPU presentation remains preview/best-effort.

4.2 High-resolution CEL decision (M14 — post-1.0 research)

M14 is not a v1.0 gate. The current --high-res mode remains opt-in; the default stays 320x240 + output filtering. Track the research in HighResolutionCelResearch.md.

Current --high-res mode is measured per tested title (post-1.0).
True 640x480 prototype is validated or rejected with evidence (post-1.0).
2x supersampling prototype has frame-time/allocations data (post-1.0).
GPU CEL feasibility note has a parity/performance estimate (post-1.0).
The default remains compatibility-safe 320x240 + output filtering unless a title is explicitly validated.

4.3 Existing soak evidence (12-title set)

Suggested soak command:

$env:FIVEDO_GAMES = "J:\Panasonic 3DO"
$env:FIVEDO_DISC  = "$env:FIVEDO_GAMES\Wolfenstein 3D (USA).chd"

dotnet run -c Release --project src/FiveDo.Cli -- run `
  "$env:FIVEDO_DISC" --bios bios/panafz1.bin --frames 36000 `
  --nvram artifacts/soak-w3d.ram --frame-out artifacts/soak-w3d.png --json

A known hang at a documented frame is acceptable for v1.0 if KnownIssues.md says so. A new crash, silent corruption, or save-state regression is not.

5. Packaging and artifacts

Hard gate: a release must produce and publish runnable bundles/binaries. A source-only tag or GitHub release is not a complete release.

5.1 Single-file decision

A self-contained single-file publish embeds a complete .NET runtime in each executable (roughly 70 MB per app before compression) and duplicates it. The release therefore uses framework-dependent single-file apphosts: each app is one executable, the .NET runtime is not embedded, and the bundle contains no runtime folder. Users must install the .NET 10 runtime on their machine.

This is the required distribution model for v1.0.0: no .NET runtime in the binaries or inside the bundle.

6. Release mechanics and sign-off

Bump FiveDoVersion.Version in src/FiveDo.Core/FiveDoVersion.cs to 1.0.0 (and Directory.Build.props).
Move the CHANGELOG.md [Unreleased] section to 1.0.0 and date it.
Write release notes: feature summary, supported platforms, supported titles, known issues, BIOS/disc requirements, license.
Tag the release (v1.0.0).
Attach the unified bundles and checksums to the release (published on GitHub: https://github.com/purelogiccode/5DO/releases/tag/v1.0.0).
CI release workflow builds the bundles, writes SHA256SUMS.txt, updates the release, and removes obsolete per-component assets.
Update README, docs/Status.md, docs/Compatibility.md, docs/KnownIssues.md, docs/WhatsNew.md, and the release docs.
Record the post-1.0 backlog in docs/ImplementationPlan.md.

Sign-off	Name	Date
Release owner	Project owner (purelogiccode)	2026-11-02
Legal / distribution	Approved: FreeDO modified GNU LGPL, donationware	2026-11-02
Compatibility / QA	Documented-compatibility scope: 593/594 render, 12-title matrix; Linux x64 full suite	2026-11-02
Packaging / CI	Unified framework-dependent bundles, no bundled runtime, release workflow	2026-11-02

7. Post-1.0 backlog (explicitly not release gates)

Finish a full Road Rash race and script Alone's inventory/exploration.
Add input/gameplay scripts for Gex, Need for Speed, SSF2 Turbo, Total Eclipse, Killing Time, Theme Park, and Return Fire.
M13.5 in-game/visual review and M13.6 high-resolution pass.
M14 high-resolution CEL research (true 640x480, supersampling, GPU CEL feasibility).
Continue CD/CLIO/MADAM/ARM timing triage with the Opera differential harness.
GLES 3.1, desktop arm64 hardware, 100/150/200% DPI, and Linux/macOS launch validation if not claimed for v1. Raspberry Pi, Android/iOS, and WebAssembly are out of scope.
Tier B 1080p60 timing, 3D CEL profiling, hot-path optimization, and the same-machine relative benchmark gate on stable CI hardware.
MSIX/dmg/AppImage installers, signing/notarization, and file associations. Frontend NativeAOT audio remains unvalidated; the CLI AOT path is validated.
ViewModel tests and UI polish.
Optional M12 managed ARM JIT (profile first; not needed for v1).

8. Definition of done

v1.0 is done when sections 1-6 are complete and signed off, the supported set has been soaked, the compatibility matrix and known issues are honest, and the release artifacts can be extracted and started on every claimed platform. Full compatibility is not part of this definition. M13.5/M13.6 visual/high-resolution review and M14 research are post-1.0.

Navigation Menu

Repository navigation

ReleaseChecklist.md

ReleaseChecklist.md

Release Checklist

1.1.0 maintenance gate

1.3.0 field-handling gate

1.4.0 feature and accuracy gate

1.5.0 accuracy and GPU-HQx gate

1.6.0 compatibility-completion gate

Cover-art hosting gate

1.2.2 performance and library gate

1.2.1 arm64 packaging gate

1.2.0 feature gate

0. Recommended v1 scope

1. Scope and decisions

2. Legal and attribution (hard gate)

3. Build, test, and CI

4. Stability and compatibility

4.1 Full-collection compatibility sweep (M13)

4.2 High-resolution CEL decision (M14 — post-1.0 research)

4.3 Existing soak evidence (12-title set)

5. Packaging and artifacts

5.1 Single-file decision

6. Release mechanics and sign-off

7. Post-1.0 backlog (explicitly not release gates)

8. Definition of done

FilesExpand file tree

ReleaseChecklist.md

Latest commit

History

ReleaseChecklist.md

File metadata and controls

Release Checklist

1.1.0 maintenance gate

1.3.0 field-handling gate

1.4.0 feature and accuracy gate

1.5.0 accuracy and GPU-HQx gate

1.6.0 compatibility-completion gate

Cover-art hosting gate

1.2.2 performance and library gate

1.2.1 arm64 packaging gate

1.2.0 feature gate

0. Recommended v1 scope

1. Scope and decisions

2. Legal and attribution (hard gate)

3. Build, test, and CI

4. Stability and compatibility

4.1 Full-collection compatibility sweep (M13)

4.2 High-resolution CEL decision (M14 — post-1.0 research)

4.3 Existing soak evidence (12-title set)

5. Packaging and artifacts

5.1 Single-file decision

6. Release mechanics and sign-off

7. Post-1.0 backlog (explicitly not release gates)

8. Definition of done