From eb1776e61481389be36791eb7b0b2d051c4d41a8 Mon Sep 17 00:00:00 2001 From: Zwitschi Date: Sat, 31 Oct 2026 13:01:29 +0100 Subject: [PATCH] Update architecture docs and README with versioning, CI/CD, and release management details --- README.md | 2 +- docs/architecture.md | 28 ++++++++++++++++++++++++++++ 2 files changed, 29 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 061db93..1ad9554 100644 --- a/README.md +++ b/README.md @@ -168,7 +168,7 @@ The unit test runner is the project's own lightweight harness (no editor plugin ## Architecture -The full arc42-style architecture documentation lives in [`docs/architecture.md`](docs/architecture.md). It covers goals, constraints, context, solution strategy, building blocks, runtime views, deployment, cross-cutting concepts, quality requirements, risks, and a glossary. +The full arc42-style architecture documentation lives in [`docs/architecture.md`](docs/architecture.md). It covers goals, constraints, context, solution strategy, building blocks, runtime views, deployment, cross-cutting concepts, quality requirements, risks, a glossary, the CI/CD build pipeline, semantic versioning, and release management. ## Project Documentation diff --git a/docs/architecture.md b/docs/architecture.md index c07a0d5..006bc7d 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -28,6 +28,15 @@ This document follows the structure of the arc42 architecture documentation temp - Venue-specific policies must be configurable rather than hard-coded into individual NPCs. - The game must preserve the de-escalation-first design described in [`PLAN.md`](../PLAN.md). - The project uses the repository workflow described in [`AGENTS.md`](../AGENTS.md). +- The project follows [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`). + +### Version management + +- **MAJOR** — incompatible changes to the game's core systems, save format, or public-facing behavior. +- **MINOR** — new venues, NPC archetypes, systems, or features that are backward compatible. +- **PATCH** — bug fixes and small polish that do not change behavior. + +The single source of truth for the version is `config/version` in `project.godot` (currently `0.1.0`). Each release is tagged in git as `v` (e.g. `v0.1.0`). The `0.x` series is pre-1.0, so MINOR bumps may introduce breaking changes while the prototype is still stabilizing. `tools/build_releases.sh` and `tools/publish_release.sh` read the version from `project.godot`, so bumping it there is the only required step before a release. The full bump checklist lives in [`RELEASING.md`](RELEASING.md). ## 3. Context and Scope @@ -103,6 +112,25 @@ The initial target is a single-player local game. The expected runtime consists Future options include external analytics, cloud saves, or replay sharing, but they are not part of the initial architecture. +### CI/CD build pipeline + +A continuous-integration pipeline keeps the headless test suite green on every change, with a planned extension to build and publish release artifacts automatically. + +- **CI workflow** (`.github/workflows/ci.yml`) runs on every push to `main` and on every pull request. It installs the pinned Godot 4.3 editor, caches the `.godot` import artifacts, imports the project to build the class cache, and runs the headless test suite (`res://src/test/test_runner.gd`). The job fails on a non-zero exit code or any `SCRIPT ERROR` in the output. +- **Planned extension** grows the pipeline from "test only" to "test, build, and publish": a test stage (headless tests plus a `--quit-after 120` boot smoke test as the merge gate), a build stage (install export templates, run `tools/build_releases.sh`), and a publish stage (on a version tag, upload artifacts via `tools/publish_release.sh` with a `GITEA_TOKEN` secret). +- **Hosting note:** the repository lives on Gitea/Forgejo (`https://git.allucanget.biz/zwitschi/security-game`); the workflow is authored for GitHub Actions and should be mirrored or ported to the host's own runner if Actions is unavailable there. Export templates must match the pinned engine version, and macOS builds are unsigned (production releases need notarization or clear quarantine guidance). + +### Release management + +Releases are produced from a tagged commit and published to the repository host's release page, where the README "Downloads" links point. + +- `export_presets.cfg` — committed Linux, Windows Desktop, and macOS export presets so builds are reproducible. +- `tools/build_releases.sh` — exports all three desktop artifacts into `build/`, named `step-line--.`. +- `tools/publish_release.sh` — creates a release and uploads the artifacts via the Gitea/Forgejo API (requires `GITEA_TOKEN`). +- [`RELEASING.md`](RELEASING.md) — step-by-step guide and release checklist. + +The release process is: bump the version, run the full test suite and boot smoke test, run `tools/build_releases.sh`, run `tools/publish_release.sh` (or create the release via the web UI), and verify the README "Downloads" links resolve to the new release. + ## 8. Cross-Cutting Concepts - **Event-based incident recording:** Important actions emit records consumed by evidence, reputation, and review systems.