Release Checklist¶

Adopted: 2026-10-26 Release timing: v1.2.1 is the current release; unified Windows/Linux/macOS x64/arm64 bundles are built from the same gates used for v1.0.0 and v1.1.0. 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 adds arm64 bundles. 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¶

• Bump FiveDoVersion.Version and Directory.Build.props to 1.1.0.
• Move the OpenAL Soft license text to docs/OpenAL-Soft-COPYING.txt and remove the nested docs/licenses/ folder.
• Every bundle copies the license to docs/OpenAL-Soft-COPYING.txt.
• Game library deduplicates copies of the same game by 3DO game ID.
• Desktop status bar no longer shows the frame ... PC ... cyc counter.
• CLI and desktop logging route through Serilog; warning-and-higher events reach the bug-report API with environment, error, and exception blocks.
• CLI and desktop launch statistics call the ApplicationStats endpoint.
• Full suite 1,475/1,475, dotnet format --verify-no-changes, and jb inspectcode --severity=WARNING are clean.
• CI cross-publishes the macOS x64 bundle on Linux and validates its Mach-O architecture, avoiding the unavailable hosted macOS runner.
• Build the three bundles. Windows and Linux bundles passed CLI selftest and desktop --smoke-test; the macOS x64 bundle is cross-published on Linux and validated as Mach-O x86_64, matching the v1.0.0 runtime-validation scope.
• Publish v1.1.0 and verify SHA256SUMS.txt.

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.

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:

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¶

• dotnet build 5DO.sln -c Release passes with 0 warnings and 0 errors (1.0.0).
• dotnet test tests/FiveDo.Tests/FiveDo.Tests.csproj -c Release passes: 1,597/1,597 with the current tree.
• dotnet format 5DO.sln --verify-no-changes passes.
• jb inspectcode 5DO.sln --severity=WARNING reports 0 warnings and 0 errors (2026-11-02).
• CI is green on the supported runners (2026-11-02): Windows, Linux, macOS, NativeAOT CLI/frontend, unified bundle builds, CodeQL, docs, and dependency review.
• Synthetic benchmark --gate passes: 2.28 ms/frame core mean, 4.03 ms core p99, 4.66 ms total p99, 0 bytes/frame.
• Bundle CLI smoke test passes: --version, selftest --json, bench --frames 2 --json, info, and a 300-frame disc run.
• Bundle frontend smoke test passes (--smoke-test).
• Linux x64 smoke test passes (2026-11-02): the full test suite 1,473/1,473, CLI selftest, bench, info, bios info, a 3,000-frame Wolfenstein boot, non-silent audio, and the frontend --smoke-test on Linux Mint 22.3. The GL probe timed out under llvmpipe, so Linux GPU presentation is preview/best-effort; see Compatibility.md §10.3.
• NativeAOT CLI/frontend smoke tests are not shipped in 1.0.0; the framework-dependent single-file bundles are the release artifacts.

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-updates
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)¶

• Wolfenstein 3D soak: 36,000 frames, exit 0; 0x0814F039.
• Lemmings soak: 36,000 frames, exit 0; 0x9939D345.
• Road Rash soak: 36,000 frames, exit 0; 0xBDC2DBEA.
• Alone in the Dark soak: 36,000 frames, exit 0; 0xBA7F2C8C.
• Space Ace soak: 36,000 frames, exit 0; 0xFD0F5B72.
• Gex, Need for Speed, SSF2 Turbo, Total Eclipse, Killing Time, Theme Park, and Return Fire: 36,000-frame state soak from the archived 12k states on 1.0.0 candidate; all exit 0. The source discs for these seven are not present on this machine, so this is a continuation soak, not a fresh boot.
• Save/load roundtrip on each showcase title: zero-frame hash matches and two 120-frame continuations are identical (see Compatibility.md §10.2).
• Audio is non-silent 44.1 kHz stereo on the showcase titles and uses the exact 44,100-sample clock (10.000 s per 600 frames). Road Rash's race mix clips (2,036 frames in a 92k-state capture), the 36k Lemmings gameplay state happened to be silent while its 23k state is non-silent, and Theme Park's menu is silent; all are documented in TestCorpus.md 1.5a2. Live OpenAL output, audio-driven pacing, WAV analysis, and AOT CLI audio are validated. The 2026-10-28 pass fixed the remaining live-output crackle (buffer ownership) and validated it with the PCM tap: 0 OpenAL errors, 0 underruns, and 0 discontinuities across 2,345 buffer boundaries.
• Keyboard input works on the showcase titles through the scripted runs; gamepad mapping and merge behavior are covered by unit tests, with hardware validation still platform-specific.
• Screenshots and save slots are covered by unit tests and the frontend smoke path; a manual click-through was not repeated in this session.
• OpenGL path works (WGL and ANGLE/GLES Accurate parity, 0 different pixels); CPU fallback is covered by the existing tests and smoke path.
• docs/Compatibility.md updated with the release matrix and §10.2 soak evidence.
• docs/KnownIssues.md updated with the Space Ace long no-input wait and the remaining platform/gameplay limitations.

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.

• Publish the CLI and desktop app as framework-dependent single-file apphosts (PublishSingleFile=true, PublishTrimmed=false).
• Do not copy the .NET runtime into the bundle. Users must install the .NET 10 runtime on their machine; PACKAGE.txt and the README record the requirement.
• Build one bundle per system with packaging/package-bundle.ps1: 5do-<version>-win-x64.zip, 5do-<version>-linux-x64.tar.gz, 5do-<version>-osx-x64.tar.gz.
• Each bundle contains both executables, README.md, LICENSE, THIRD-PARTY-NOTICES.md, whatsnew.md, docs/Licensing.md, docs/ReleaseLegalReview.md, docs/OpenALSoft.md, docs/OpenAL-Soft-COPYING.txt, the release notes, and PACKAGE.txt.
• Remove PDB and XML documentation files; they are build outputs, not runtime dependencies.
• Keep the native OpenAL Soft/Skia/ANGLE libraries beside the apphosts so the LGPL replacement rights remain practical.
• PACKAGE.txt records component bundle, RID, version, commit, UTC build time, the .NET 10 runtime requirement, launch commands, and the no-BIOS/no-disc notice.
• No runtime folder, PDBs, XML docs, or copyrighted content in release bundles.
• Extract each bundle to a clean folder and run the CLI/frontend smoke test.
• SHA-256 checksums generated for every bundle.
• CI builds the Windows/Linux bundles on their native runners, cross-publishes the macOS x64 bundle on Linux, verifies that no runtime or XML files are present, and publishes them with the checksums; the docs workflow updates GitHub Pages and the wiki.
• Local copies are written to src/FiveDo.Frontend.Avalonia/bin/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.

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.