117 lines
4.7 KiB
Markdown
117 lines
4.7 KiB
Markdown
# Releasing HOT-Step CPP — agent runbook
|
||
|
||
How to cut and publish a release, plus the non-obvious gotchas. Written for an
|
||
agent (or human) driving the process with the `gh` CLI on Windows/Git-Bash.
|
||
|
||
## TL;DR
|
||
|
||
Releases are cut by **pushing a `vX.Y.Z` tag**. The `Release` workflow builds
|
||
every platform and creates a **draft** GitHub Release; you review and publish it.
|
||
A separate `Cache Warm` workflow keeps the engine build cache on `master` so
|
||
release builds take ~10–15 min instead of ~1.5h for the CUDA jobs.
|
||
|
||
## Prerequisites
|
||
|
||
- `gh` authenticated (as `scragnog`).
|
||
- On `master`, working tree clean, everything committed **and pushed**.
|
||
- Pick a semver version **without a hyphen**: `vX.Y.Z` (hyphens are reserved for
|
||
test/pre-release tags — see gotchas).
|
||
|
||
## 1. (Optional) Compile-test before releasing
|
||
|
||
To verify CI compiles without cutting a real release, push a throwaway
|
||
**hyphenated** tag — it triggers the same build pipeline but is ignored by the
|
||
changelog logic:
|
||
|
||
```bash
|
||
git tag -a vX.Y.Z-CI-Test -m "compile test" && git push origin vX.Y.Z-CI-Test
|
||
# ...watch it (section 3)... then delete when done:
|
||
gh release delete vX.Y.Z-CI-Test --cleanup-tag --yes # removes draft + remote tag
|
||
git tag -d vX.Y.Z-CI-Test
|
||
```
|
||
|
||
Re-pushing the **same** `-CI-Test` name is free (delete remote+local, recreate,
|
||
push). Tags cannot be renamed.
|
||
|
||
## 2. Cut the release
|
||
|
||
```bash
|
||
git tag -a vX.Y.Z -m "vX.Y.Z — <one-line summary>"
|
||
git push origin vX.Y.Z
|
||
```
|
||
|
||
This triggers `Release` → builds Windows (cuda13.1 / cuda12.8 / vulkan / cpu),
|
||
Linux (same four), macOS (Metal) → creates a **draft** release with **22 assets**
|
||
(11 archives + 11 `.sha256`).
|
||
|
||
To change the commit or re-run: delete + re-push the tag (it rebuilds).
|
||
|
||
## 3. Monitor
|
||
|
||
```bash
|
||
gh run list --limit 5
|
||
gh run view <run-id> # per-job status + timings
|
||
```
|
||
|
||
To read a **failed/cancelled job's** log while the run is still in progress
|
||
(`gh run view --log` won't show it yet), pull it from the API:
|
||
|
||
```bash
|
||
MSYS_NO_PATHCONV=1 gh api repos/scragnog/HOT-Step-CPP/actions/jobs/<job-id>/logs > log.txt
|
||
```
|
||
|
||
`MSYS_NO_PATHCONV=1` stops Git-Bash rewriting the leading-slash API path into a
|
||
filesystem path.
|
||
|
||
## 4. Publish
|
||
|
||
The workflow leaves the release as a **draft**. Verify the asset count (18) and
|
||
the `What's Changed` notes, then:
|
||
|
||
```bash
|
||
gh release view vX.Y.Z --json assets --jq '.assets | length' # expect 22
|
||
gh release edit vX.Y.Z --draft=false --latest
|
||
```
|
||
|
||
## 5. Cleanup
|
||
|
||
Delete any leftover test tags and their drafts (see section 1).
|
||
|
||
## Build caching — why releases are fast (and how it breaks)
|
||
|
||
- **GitHub Actions caches are ref-scoped.** A cache saved by one tag run is NOT
|
||
visible to a different tag run — only **default-branch (`master`) caches** are
|
||
visible to every run, including release tags. So releases can only reuse a
|
||
cache that was created on `master`.
|
||
- **`.github/workflows/cache-warm.yml`** builds the engine on `master` (when
|
||
`engine/ggml` or `engine/CMakeLists.txt` change, or via manual dispatch) and
|
||
saves the build dir under the **same cache keys** `release.yml` uses. Release
|
||
runs restore it and skip the CUDA compile (the long part).
|
||
- **Timings:** cold (no master cache) CUDA jobs ≈ 1.5h each; warm ≈ 7–13 min.
|
||
- **If CUDA suddenly rebuilds slow:** the master cache is missing/stale. Re-warm
|
||
it: GitHub → Actions → **Cache Warm** → *Run workflow* (on `master`). It also
|
||
auto-runs when `engine/ggml`/`CMakeLists.txt` change.
|
||
- Cache reuse depends on git-restored source mtimes (incl. the **ggml submodule**
|
||
— its `.cu` files live in the submodule's own history, not the superproject).
|
||
|
||
## Gotchas / lessons learned
|
||
|
||
- **Windows runner is pinned to `windows-2022`.** Do NOT switch to
|
||
`windows-latest` — that's windows-2025, whose MSVC (`_MSC_VER >= 1950`) is
|
||
rejected by CUDA 12.8/13.1 `nvcc` (`host_config.h`: VS 2017–2022 only).
|
||
- **Any pushed `v*` tag triggers the Release pipeline.** Use `vX.Y.Z` for
|
||
releases and `-CI-Test` (or other hyphenated) tags for throwaway checks; delete
|
||
them afterward. Don't push local feature tags that match `v*`.
|
||
- **Changelog range** = commits since the previous **non-hyphenated** tag
|
||
(`git describe ... --exclude '*-*'`). This is why a stray `vX-CI-Test` tag must
|
||
not be treated as a release; the exclude guard handles it, but still clean up.
|
||
- **The release is a draft** — it does not auto-publish. Review before going live.
|
||
- **Cache key** = `cmake-<runner>-<variant>-<hash(engine/ggml, CMakeLists)>`.
|
||
Changing the runner image invalidates it (compiler abs-paths bake into
|
||
`CMakeCache.txt`); the key includes the runner image to prevent stale restores.
|
||
|
||
## Reference
|
||
|
||
- Workflows: [`.github/workflows/release.yml`](../.github/workflows/release.yml),
|
||
[`.github/workflows/cache-warm.yml`](../.github/workflows/cache-warm.yml)
|