scawful/yaze
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
476dd1cd1cc2653f52abb27e93b01db18974fdf6
yaze/docs/internal/release-checklist-template.md
scawful 476dd1cd1c backend-infra-engineer: Release v0.3.3 snapshot
2025-11-21 21:35:50 -05:00

12 KiB
Raw Blame History

Release Checklist Template

Release Version: vX.Y.Z Release Coordinator: [Agent/Developer Name] Target Branch: develop → master Target Date: YYYY-MM-DD Status: PLANNING | IN_PROGRESS | READY | RELEASED Last Updated: YYYY-MM-DD

Pre-Release Testing Requirements

1. Platform Build Validation

All platforms must build successfully with zero errors and minimal warnings.

Windows Build

  • Debug build passes: cmake --preset win-dbg && cmake --build build
  • Release build passes: cmake --preset win-rel && cmake --build build
  • AI build passes: cmake --preset win-ai && cmake --build build --target z3ed
  • No new warnings: Compare warning count to previous release
  • Smoke test: pwsh -File scripts/agents/windows-smoke-build.ps1 -Preset win-rel -Target yaze
  • Blocker Status: NONE | [Description if blocked]

Linux Build

  • Debug build passes: cmake --preset lin-dbg && cmake --build build
  • Release build passes: cmake --preset lin-rel && cmake --build build
  • AI build passes: cmake --preset lin-ai && cmake --build build --target z3ed
  • No new warnings: Compare warning count to previous release
  • Smoke test: scripts/agents/smoke-build.sh lin-rel yaze
  • Blocker Status: NONE | [Description if blocked]

macOS Build

  • Debug build passes: cmake --preset mac-dbg && cmake --build build
  • Release build passes: cmake --preset mac-rel && cmake --build build
  • AI build passes: cmake --preset mac-ai && cmake --build build --target z3ed
  • Universal binary passes: cmake --preset mac-uni && cmake --build build
  • No new warnings: Compare warning count to previous release
  • Smoke test: scripts/agents/smoke-build.sh mac-rel yaze
  • Blocker Status: NONE | [Description if blocked]

2. Test Suite Validation

All test suites must pass on all platforms.

Unit Tests

  • Windows: ./build/bin/yaze_test --unit (100% pass)
  • Linux: ./build/bin/yaze_test --unit (100% pass)
  • macOS: ./build/bin/yaze_test --unit (100% pass)
  • Zero regressions: No new test failures vs previous release
  • Coverage maintained: >80% coverage for critical paths

Integration Tests

  • Windows: ./build/bin/yaze_test --integration (100% pass)
  • Linux: ./build/bin/yaze_test --integration (100% pass)
  • macOS: ./build/bin/yaze_test --integration (100% pass)
  • ROM-dependent tests: All pass with reference ROM
  • Zero regressions: No new test failures vs previous release

E2E Tests

  • Windows: ./build/bin/yaze_test --e2e (100% pass)
  • Linux: ./build/bin/yaze_test --e2e (100% pass)
  • macOS: ./build/bin/yaze_test --e2e (100% pass)
  • GUI workflows validated: Editor smoke tests pass
  • Zero regressions: No new test failures vs previous release

Performance Benchmarks

  • Graphics benchmarks: No >10% regression vs previous release
  • Load time benchmarks: ROM loading <3s on reference hardware
  • Memory benchmarks: No memory leaks detected
  • Profile results: No new performance hotspots

3. CI/CD Validation

All CI jobs must pass successfully.

  • Build job (Linux): ✅ SUCCESS
  • Build job (macOS): ✅ SUCCESS
  • Build job (Windows): ✅ SUCCESS
  • Test job (Linux): ✅ SUCCESS
  • Test job (macOS): ✅ SUCCESS
  • Test job (Windows): ✅ SUCCESS
  • Code Quality job: ✅ SUCCESS (clang-format, cppcheck, clang-tidy)
  • z3ed Agent job: ✅ SUCCESS (optional, if AI features included)
  • Security scan: ✅ PASS (no critical vulnerabilities)

CI Run URL: [Insert GitHub Actions URL]

4. Code Quality Checks

  • clang-format: All code formatted correctly
  • clang-tidy: No critical issues
  • cppcheck: No new warnings
  • No dead code: Unused code removed
  • No TODOs in critical paths: All critical TODOs resolved
  • Copyright headers: All files have correct headers
  • License compliance: All dependencies have compatible licenses

5. Symbol Conflict Verification

  • No duplicate symbols: scripts/check-symbols.sh passes (if available)
  • No ODR violations: All targets link cleanly
  • Flag definitions unique: No FLAGS_* conflicts
  • Library boundaries clean: No unintended cross-dependencies

6. Configuration Matrix Coverage

Test critical preset combinations:

  • Minimal build: cmake --preset minimal (no gRPC, no AI)
  • Dev build: cmake --preset dev (all features, ROM tests)
  • CI build: cmake --preset ci-* (matches CI environment)
  • Release build: cmake --preset *-rel (optimized, no tests)
  • AI build: cmake --preset *-ai (gRPC + AI runtime)

7. Feature-Specific Validation

GUI Application (yaze)

  • Launches successfully: No crashes on startup
  • ROM loading works: Can load reference ROM
  • Editors functional: All editors (Overworld, Dungeon, Graphics, etc.) open
  • Saving works: ROM modifications persist correctly
  • No memory leaks: Valgrind/sanitizer clean (Linux/macOS)
  • UI responsive: No freezes or lag during normal operation

CLI Tool (z3ed)

  • Launches successfully: z3ed --help works
  • Basic commands work: z3ed rom info zelda3.sfc
  • AI features work: z3ed agent chat (if enabled)
  • HTTP API works: z3ed --http-port=8080 serves endpoints (if enabled)
  • TUI functional: Terminal UI renders correctly

Asar Integration

  • Patch application works: Can apply .asm patches
  • Symbol extraction works: Symbols loaded from ROM
  • Error reporting clear: Patch errors show helpful messages

ZSCustomOverworld Support

  • v3 detection works: Correctly identifies ZSCustomOverworld ROMs
  • Upgrade path works: Can upgrade from v2 to v3
  • Extended features work: Multi-area maps, custom sizes

8. Documentation Validation

  • README.md up to date: Reflects current version and features
  • CHANGELOG.md updated: All changes since last release documented
  • Build docs accurate: Instructions work on all platforms
  • API docs current: Doxygen builds without errors
  • User guides updated: New features documented
  • Migration guide: Breaking changes documented (if any)
  • Release notes drafted: User-facing summary of changes

9. Dependency and License Checks

  • Dependencies up to date: No known security vulnerabilities
  • License files current: All dependencies listed in LICENSES.txt
  • Third-party notices: THIRD_PARTY_NOTICES.md updated
  • Submodules pinned: All submodules at stable commits
  • vcpkg versions locked: CMake dependency versions specified

10. Backward Compatibility

  • ROM format compatible: Existing ROMs load correctly
  • Save format compatible: Old saves work in new version
  • Config file compatible: Settings from previous version preserved
  • Plugin API stable: External plugins still work (if applicable)
  • Breaking changes documented: Migration path clear

Release Process

Pre-Release

  1. Branch Preparation

    • All features merged to develop branch
    • All tests passing on develop
    • Version number updated in:
      • CMakeLists.txt (PROJECT_VERSION)
      • src/yaze.cc (version string)
      • src/cli/z3ed.cc (version string)
      • README.md (version badge)
    • CHANGELOG.md updated with release notes
    • Documentation updated

  2. Final Testing

    • Run full test suite on all platforms
    • Run smoke builds on all platforms
    • Verify CI passes on develop branch
    • Manual testing of critical workflows
    • Performance regression check

  3. Code Freeze

    • Announce code freeze on coordination board
    • No new features merged
    • Only critical bug fixes allowed
    • Final commit message: "chore: prepare for vX.Y.Z release"

Release

  1. Merge to Master

    • Create merge commit: git checkout master && git merge develop --no-ff
    • Tag release: git tag -a vX.Y.Z -m "Release vX.Y.Z - [Brief Description]"
    • Push to remote: git push origin master develop --tags

  2. Build Release Artifacts

    • Trigger release workflow: .github/workflows/release.yml
    • Verify Windows binary builds
    • Verify macOS binary builds (x64 + ARM64)
    • Verify Linux binary builds
    • Verify all artifacts uploaded to GitHub Release

  3. Create GitHub Release

    • Go to https://github.com/scawful/yaze/releases/new
    • Select tag vX.Y.Z
    • Title: "yaze vX.Y.Z - [Brief Description]"
    • Description: Copy from CHANGELOG.md + add highlights
    • Attach binaries (if not auto-uploaded)
    • Mark as "Latest Release"
    • Publish release

Post-Release

  1. Verification

    • Download binaries from GitHub Release
    • Test Windows binary on clean machine
    • Test macOS binary on clean machine (both Intel and ARM)
    • Test Linux binary on clean machine
    • Verify all download links work

  2. Announcement

    • Update project website (if applicable)
    • Post announcement in GitHub Discussions
    • Update social media (if applicable)
    • Notify contributors
    • Update coordination board with release completion

  3. Cleanup

    • Archive release branch (if used)
    • Close completed milestones
    • Update project board
    • Plan next release cycle

GO/NO-GO Decision Criteria

✅ GREEN LIGHT (READY TO RELEASE)

All of the following must be true:

  • ✅ All platform builds pass (Windows, Linux, macOS)
  • ✅ All test suites pass on all platforms (unit, integration, e2e)
  • ✅ CI/CD pipeline fully green
  • ✅ No critical bugs open
  • ✅ No unresolved blockers
  • ✅ Documentation complete and accurate
  • ✅ Release artifacts build successfully
  • ✅ Manual testing confirms functionality
  • ✅ Release coordinator approval

❌ RED LIGHT (NOT READY)

Any of the following triggers a NO-GO:

  • ❌ Platform build failure
  • ❌ Test suite regression
  • ❌ Critical bug discovered
  • ❌ Security vulnerability found
  • ❌ Unresolved blocker
  • ❌ CI/CD pipeline failure
  • ❌ Documentation incomplete
  • ❌ Release artifacts fail to build
  • ❌ Manual testing reveals issues

Rollback Plan

If critical issues are discovered post-release:

  1. Immediate: Unlist GitHub Release (mark as pre-release)
  2. Assess: Determine severity and impact
  3. Fix: Create hotfix branch from master
  4. Test: Validate fix with full test suite
  5. Release: Tag hotfix as vX.Y.Z+1 and release
  6. Document: Update CHANGELOG with hotfix notes

Blockers and Issues

Active Blockers

Blocker Severity Description Owner Status ETA
[Add blockers as discovered]

Resolved Issues

Issue Resolution Date
[Add resolved issues]

Platform-Specific Notes

Windows

  • Compiler: MSVC 2022 (Visual Studio 17)
  • Generator: Ninja Multi-Config
  • Known Issues: [List any Windows-specific considerations]
  • Verification: Test on Windows 10 and Windows 11

Linux

  • Compiler: GCC 12+ or Clang 16+
  • Distros: Ubuntu 22.04, Fedora 38+ (primary targets)
  • Known Issues: [List any Linux-specific considerations]
  • Verification: Test on Ubuntu 22.04 LTS

macOS

  • Compiler: Apple Clang 15+
  • Architectures: x86_64 (Intel) and arm64 (Apple Silicon)
  • macOS Versions: macOS 12+ (Monterey and later)
  • Known Issues: [List any macOS-specific considerations]
  • Verification: Test on both Intel and Apple Silicon Macs

References

Last Review: YYYY-MM-DD Next Review: YYYY-MM-DD (after release)

Reference in New Issue View Git Blame Copy Permalink