release

---
name: release
description: >
license: MIT
---

# 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

```markdown
## 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.