Release Process

Release Process

Version Scheme

Firestaff uses semantic versioning: MAJOR.MINOR.PATCH (e.g., 3.0.282). The version is set in CMakeLists.txt:

project(Firestaff VERSION 3.0.282 LANGUAGES C)

Release notes format

Every version block in RELEASE_NOTES.md is grouped by game. It contains DM1, DM2, CSB, Nexus and Theron; each game contains Added, Changed and Removed. A category with no change contains exactly None.. Non-empty bullets name the affected function, subsystem, command, screen or feature in backticks.

Creating a release

1. Bump version in CMakeLists.txt.

2. Write release notes in RELEASE_NOTES.md (add a section headed # Firestaff vX.Y.Z). The section must contain exactly these functional delta categories, each with concrete bullets:

   # Firestaff vX.Y.Z
   
   ## DM1
   ### Added
   - None.
   ### Changed
   - `dm1_feature`: describe the concrete change.
   ### Removed
   - None.
   
   ## DM2
   ### Added
   - None.
   ### Changed
   - None.
   ### Removed
   - None.
   
   ## CSB
   ### Added
   - None.
   ### Changed
   - None.
   ### Removed
   - None.
   
   ## Nexus
   ### Added
   - None.
   ### Changed
   - None.
   ### Removed
   - None.
   
   ## Theron
   ### Added
   - None.
   ### Changed
   - None.
   ### Removed
   - None.

   Name the affected function, subsystem, command, screen or feature in every non-empty bullet. Do not use aggregate wording such as “various updates” or generic release summaries. A release with no delta in a category must say None. explicitly. The release workflow rejects notes that do not meet this contract.

3. Update active TODO and DONE ledgers as needed: TODO.md for cross-game work, TODO-<game>.md for active game work, and the matching DONE*.md only after evidence-backed completion. Then run scripts/sync_wiki.sh in the release workflow to publish docs/wiki/.

4. Commit the version bump and documentation.

5. Tag with v prefix only when a release is explicitly requested.

6. Push the tag only for that release.

The GitHub Actions release workflow triggers automatically on v* tags.

Ordinary documentation and code work is pushed to main without creating a tag or GitHub Release.

CI/CD Pipeline

Verify Workflow (verify.yml)

Runs on every push and PR. Tests on:

• Ubuntu 24.04
• macOS 14
• Windows 2022

Checks: build, test suite, compiler warnings, asset hygiene (no game data committed).

Release Workflow (release.yml)

Triggers on v* tags or manual workflow_dispatch. Jobs:

1. Preflight — validates the version against CMakeLists.txt and verifies that the selected release-notes section names added, changed and removed functions/features before extracting it
2. macOS — builds x86_64 (Intel) and arm64 (Apple Silicon) in parallel
   • Produces: .dmg, .zip
   • Bundles: Artpack Studio, Dungeon Studio, Savegame Editor
   • Runs Phase A and Audio smoke probes
3. Windows — builds x86_64 via MSYS2 UCRT64
   • Produces: portable .zip, Inno Setup installer .exe
   • Bundles: Artpack Studio, Dungeon Studio, Savegame Editor
4. Linux — builds x86_64 and arm64 in parallel
   • Produces: .deb, .rpm
   • x86_64 also produces Steam Deck pacman .pkg.tar.zst and AppImage
   • SDL3 built from source (pinned to release-3.2.14)
5. iOS — builds arm64 on macOS 14
   • Cross-compiles with iOS toolchain (deployment target iOS 14.0)
   • SDL3 built as static library for iOS
   • Produces: .ipa (ad-hoc signed, AltStore Classic sideloadable)
6. Android — builds arm64 on Ubuntu 24.04
   • Cross-compiles with Android NDK 27 (API 24, arm64-v8a)
   • SDL3 built as shared library for Android
   • Produces: .apk (debug-signed)
7. Publish — creates/updates the GitHub Release
   • Downloads all platform artifacts
   • Generates release notes from RELEASE_NOTES.md
   • Creates combined SHA-256 checksum manifest
   • Uploads all artifacts to the GitHub Release

SDL3 Version

All platform builds pin SDL3 to release-3.2.14 via the SDL3_TAG environment variable.

Release Artifacts

Platform	Artifacts	Architecture
macOS	.dmg, .zip	x86_64, arm64
Windows	.zip, .exe (installer)	x86_64
Linux	.deb, .rpm	x86_64, arm64
Steam Deck	.pkg.tar.zst, .AppImage	x86_64
iOS	.ipa	arm64
Android	.apk	arm64

Each platform artifact set includes a .sha256 checksum file. A combined all-assets.sha256 manifest covers every artifact in the release.

Pre-commit Hooks (Lefthook)

Three checks run on every commit:

• newline_eof: all committed files must end with a newline
• trailing_whitespace: no trailing whitespace allowed
• no_game_data_payloads: original game data files (DUNGEON.DAT, GRAPHICS.DAT, etc.) must never be tracked by git

Manual Dispatch

The release workflow can also be triggered manually via workflow_dispatch with optional inputs:

• version: override release version (defaults to CMakeLists.txt version)
• draft: create as draft release
• prerelease: mark as prerelease