release

name

release

description

GitHub release management for OpenChaos — guides user through building, packaging, and publishing releases, and generates release notes with the established format. Use this skill whenever the user asks to create/prepare a release, write release notes, generate a release description, or mentions publishing to GitHub releases. Trigger on: "релиз", "release", "release notes", "описание релиза", "напиши описание", "подготовь релиз", "сделай релиз", "write release notes", "generate release description".

Release Management

This skill covers two workflows: guiding the user through the release process, and generating release notes.

Part 1: Release process guide

When the user asks to create or prepare a release, walk them through these steps. You do NOT execute build/git commands yourself (per project rules — user builds manually). Just tell the user what to do.

Steps to communicate to the user:

⚠️ Before tagging — verify third-party license versions (MANDATORY). Open THIRD_PARTY_LICENSES.md and confirm the listed versions (SDL3, OpenAL Soft, FFmpeg, fmt, nlohmann/json) match what vcpkg actually built. Get the real versions from new_game/vcpkg_installed/<triplet>/share/<port>/vcpkg.spdx.json (field versionInfo; drop the trailing #N — that is the vcpkg port revision, not the library version). OpenAL Soft and FFmpeg are LGPL and statically linked, so the "Source (this exact version)" links in that file MUST point to the exact shipped versions. If anything drifted (e.g. a vcpkg baseline bump changed FFmpeg), update the versions, the source links, and the LGPL version numbers before releasing. This is a legal requirement, not cosmetic.

⚠️ Bump the version constant FIRST (MANDATORY, do not skip). Update OPENCHAOS_VERSION in new_game/src/version.h to the new X.Y.Z before tagging. This constant is baked into the binary — window title, credits, and the HUD version label all read it. It is separate from the make release-package VERSION=<X.Y.Z> argument (that only names the zip): if you forget the constant, the binary reports the OLD version while the package name says the new one — a silent mismatch. The version bump is a code change, so it must be its own commit, and the release tag goes on that commit (not on the previous HEAD). Tell the user to bump it (you may make the edit yourself if asked — it is a one-line change in new_game/src/).

1. Bump version + commit + tag. Edit OPENCHAOS_VERSION in new_game/src/version.h → X.Y.Z, commit it, then create the tag v<X.Y.Z> on that commit. Make sure everything else is committed too.

2. Build on each platform. On every supported platform (currently Windows x64, macOS ARM64, Linux x64):

   make configure
   make build-release
   make release-package VERSION=<X.Y.Z>
   

   This creates a zip in release/dist/.

3. Test each package. Extract the zip into an Urban Chaos game folder (where the data folder is) and verify the game launches and is playable.

4. Collect all platform zips into one folder for easy access.

5. Create the GitHub release.

   • Go to GitHub -> Releases -> "Draft a new release"
   • Select the existing tag v<X.Y.Z>
   • Release title field: v<X.Y.Z> — Short description (e.g. v0.2.0 — Rendering fixes)
   • Release notes body: paste from the generated release notes (see Part 2)
   • Attach all platform zip files as release assets
   • If version is below 1.0.0 — check "Set as a pre-release"
   • Publish

6. Release notes come LAST — only after all platform builds are verified. Do NOT generate release notes during steps 1–5. Notes are written only once the user confirms the build compiles, runs, and is playable on every platform (a build may fail or reveal a bug that forces more commits — which would change the commit range the notes are built from). When the builds are verified, tell the user: "Builds verified on all platforms? Then I'll generate the release description." Wait for them to ask — see Part 2.

---

Part 2: Writing release notes

⚠️ Do not start this before the build is verified on all platforms. Writing notes is the FINAL step (see Part 1 step 6). If the user has not yet confirmed that the build compiles and runs on every platform, do not generate notes — ask whether the builds are done first. Generating notes early is wrong: a failed build or a bug found in testing can add commits that change what the notes should say.

When the user asks to write or generate release notes:

Step 1: Gather changes

Run git log vPREVIOUS..vCURRENT --oneline to get all commits between the previous and current release tags. If unsure which is the previous tag, run git tag --sort=-v:refname to list tags.

Step 2: Analyze and categorize

• If a commit message is unclear or too vague, look at the actual diff (git show <hash>) to understand what was changed
• Also check documentation diffs in commits — docs often describe what was done in more detail than the commit message itself
• Skip docs-only commits ("docs update", "small docs update", etc.)
• Write only what matters to the user. Release notes are for players/users, not developers. Skip technical implementation details (case-insensitive path resolution, fstat fixes, build scripts, etc.) — describe the user-visible result instead (e.g. "Added Linux support" instead of listing every technical change that made it work). One meaningful bullet point is better than five technical ones.
• Group remaining commits into categories based on content (see template below)
• Each change gets a clickable commit hash link

Step 3: Generate notes using this template

This template is approximate — section contents may change depending on the current project state (e.g. supported platforms, known issues, alpha vs stable). For concrete examples see https://github.com/UltimaBeaR/OpenChaos/releases

## OpenChaos vX.Y.Z — Short description

Unofficial modernization of Urban Chaos (1999). Requires original game files (Steam/GOG).

### What's new

**Category name:**
* Change description ([`abcd1234`](https://github.com/UltimaBeaR/OpenChaos/commit/abcd1234))

### Current state

This is an early alpha. The game launches and is partially playable, but expect:
* Crashes (especially on Windows)
* Visual glitches
* Fixed window resolution (no resize yet)
* No launcher or settings UI

### How to run

1. Download the zip for your platform
2. Extract into your Urban Chaos game folder (where the `data` folder is)
3. Run `OpenChaos.exe` (Windows), `OpenChaos.command` (macOS), or `OpenChaos.sh` (Linux)

### Requirements

* Original Urban Chaos game files (Steam or GOG version)
* Windows 10+ (x64), macOS 12+ (Apple Silicon), or Linux x86_64 (Steam Deck compatible)

Formatting rules

These rules are derived from v0.1.0 and v0.2.0 release notes and must be followed exactly:

• Title in release notes body: ## OpenChaos vX.Y.Z — Short description
• GitHub Release title field: vX.Y.Z — Short description (without OpenChaos prefix, e.g. v0.1.0 — First Alpha, v0.2.1 — Linux / Steam Deck support)
• Subtitle: Unofficial modernization of Urban Chaos (1999). Requires original game files (Steam/GOG). — always present, unchanged
• Commit hashes: 8-char short hashes, always clickable links: [hash](https://github.com/UltimaBeaR/OpenChaos/commit/hash)
• Multiple commits for one fix: list all: ([hash1](...), [hash2](...))
• Categories under "What's new" are bold with colon: **Gameplay:**, **Rendering bug fixes:**, **Internal:** etc. Choose categories based on actual content. Internal always goes last.
• Bullet points: use * not -
• Russian documents: if linking to documents written in Russian, add (document is in Russian) to the description
• Boilerplate sections: "Current state", "How to run", "Requirements" are copied as-is. Update them only when the project state actually changes (e.g. crashes fixed, new platforms added, resize support added).
• Output file: write the result into release_notes_vX.Y.Z.md in the project root for the user to copy, then delete afterwards

---

⚠️ Part 3: Handling user corrections — DO NOT SKIP

Every time the user corrects or changes something in the release notes:

1. Make the requested change
2. IMMEDIATELY ask: "Обновить скилл release, чтобы в будущем это учитывалось?"
3. If yes — update this SKILL.md accordingly

This step is mandatory. Do not forget to ask. User corrections = potential skill improvements.