Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

ci: the gates and the release build run on a Linux lane, and the GitHub workflows are removed

Soohong Kim3828e34969b6
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
deleted file mode 100644
index 6e46fa6..0000000
--- a/.github/workflows/ci.yml
+++ /dev/null
@@ -1,55 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-name: CI
-
-on:
- push:
- branches: [main]
- pull_request:
-
-jobs:
- test:
- name: Tests (Python ${{ matrix.python-version }})
- runs-on: ubuntu-latest
- strategy:
- fail-fast: false
- matrix:
- # Test one Python version; the installable minimum is declared separately
- # in pyproject.toml. Keep the tested version documented in README.md.
- python-version: ["3.14"]
- steps:
- - uses: actions/checkout@v4
-
- - name: Install the pipeline's required binaries (ffmpeg for video-frames, libwebp >= 1.5 for video-loop -exact)
- run: |
- sudo apt-get update -qq && sudo apt-get install -y -qq ffmpeg
- curl -fsSL https://storage.googleapis.com/downloads.webmproject.org/releases/webp/libwebp-1.6.0-linux-x86-64.tar.gz | tar -xz -C /tmp
- sudo cp /tmp/libwebp-1.6.0-linux-x86-64/bin/* /usr/local/bin/
- img2webp -h 2>&1 | grep -q -- -exact # img2webp -version exits 1 without an output file; -h is the honest probe
-
- - uses: actions/setup-python@v5
- with:
- python-version: ${{ matrix.python-version }}
-
- - name: Install (clean environment, as the quickstart does)
- run: |
- python -m venv .venv
- .venv/bin/pip install -e ".[dev]"
-
- # The user's own install path: the pinned zip, its SHA-256, the user data directory, and a
- # check frame through the binary — here on Mesa llvmpipe (docs/loop-repair.md section 1).
- - name: Install RIFE for video-loop's jump repair (sprite-gen rife install)
- run: |
- sudo apt-get install -y -qq libvulkan1 mesa-vulkan-drivers
- .venv/bin/sprite-gen rife install
-
- - name: Quickstart smoke (prepare -> extract -> compose)
- run: |
- .venv/bin/python scripts/prepare_sprite_run.py --help > /dev/null
- cp -r tests/fixtures/run /tmp/smoke-run
- .venv/bin/python scripts/extract_sprite_row_frames.py --run-dir /tmp/smoke-run
- .venv/bin/python scripts/compose_sprite_atlas.py --run-dir /tmp/smoke-run
- test -f /tmp/smoke-run/sprite-sheet-alpha.png
- test -f /tmp/smoke-run/manifest.json
-
- - name: Tests
- run: .venv/bin/python -m pytest -q
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
deleted file mode 100644
index 68875cd..0000000
--- a/.github/workflows/release.yml
+++ /dev/null
@@ -1,62 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-name: Release
-
-# A tag without a release page is the failure this exists to prevent: v2.5.3 was tagged,
-# changelogged and announced while the release page stayed at v2.5.2, so anyone reading the
-# Releases list saw the wrong version as Latest. Pushing `vX.Y.Z` now builds the page from the
-# CHANGELOG section for that version; a page that already exists is left exactly as it is.
-#
-# `workflow_dispatch` is the rehearsal: same script, same decision, `--dry-run`, so the body
-# and the asset list can be read before a tag exists. It reads the CHANGELOG of the ref it is
-# dispatched on (not of the named tag), because that ref is where the release commit is being
-# prepared. The tag push path checks out the tag itself.
-on:
- push:
- tags:
- - "v*"
- workflow_dispatch:
- inputs:
- tag:
- description: "Tag to rehearse, e.g. v2.5.3. Dry run: nothing is tagged, created or uploaded."
- required: true
- type: string
-
-permissions:
- contents: write
-
-# One release per tag at a time. Never cancel: a half-uploaded release is worse than a wait.
-concurrency:
- group: release-${{ inputs.tag || github.ref_name }}
- cancel-in-progress: false
-
-jobs:
- release:
- name: Publish the release page for the tag
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@v4
-
- - uses: actions/setup-python@v5
- with:
- # Same interpreter CI tests on; the build backend floor is pinned in pyproject.toml.
- python-version: "3.14"
-
- - name: Install the build frontend
- run: python -m pip install --upgrade build
-
- - name: Publish the release page (tag push) or rehearse it (manual dispatch)
- env:
- GH_TOKEN: ${{ github.token }}
- # Through the environment, never interpolated into the shell: a tag name is
- # attacker-controlled text on a fork, and `${{ }}` inside `run:` is substituted
- # before the shell ever sees quoting.
- INPUT_TAG: ${{ inputs.tag }}
- EVENT_NAME: ${{ github.event_name }}
- run: |
- set -euo pipefail
- if [ "${EVENT_NAME}" = "workflow_dispatch" ]; then
- echo "rehearsing ${INPUT_TAG} against ${GITHUB_REF_NAME} ($(git rev-parse --short HEAD))"
- python scripts/release_publish.py --tag "${INPUT_TAG}" --dry-run
- else
- python scripts/release_publish.py --tag "${GITHUB_REF_NAME}"
- fi
diff --git a/.gitignore b/.gitignore
index 579a235..ad0457e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -24,6 +24,6 @@ CLAUDE.md
.kuma/
.wrangler/
-# build artifacts the release workflow produces
+# build artifacts of an in-place release build (scripts/release_publish.py without --prebuilt)
/build/
/dist/
diff --git a/SECURITY.md b/SECURITY.md
index 0b19e60..270d881 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -66,5 +66,6 @@ Run the local release gate before a release:
safedeps gates run --root . --strict
```
-GitHub security workflows and branch protection are opt-in for this repository
-because they can spend runner minutes or change remote governance.
+GitHub-hosted CI is not used for this repository: the test gates and the release
+build run on the maintainer's own Linux runner through `scripts/linux_lane.sh`
+(see [docs/release.md](docs/release.md)).
diff --git a/docs/README.md b/docs/README.md
index 9ab5880..ef87793 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -125,5 +125,5 @@ grouping is derived from `sprite_gen/_modules.py`, the one taxonomy table.
|---|---|
| [interpreter.md](interpreter.md) | Why the project venv is the only interpreter (no global `python3`, no NumPy fallback) |
| [rename-gate.md](rename-gate.md) | What must move together when a vocabulary word or key is renamed |
-| [release.md](release.md) | How a vX.Y.Z tag becomes a release page, what the workflow attaches, and what stays manual |
+| [release.md](release.md) | How a vX.Y.Z tag becomes a release page, what the lane builds and the publisher attaches, and what stays manual |
| [troubleshooting.md](troubleshooting.md) | Symptoms of a pipeline that is "quietly wrong", with causes and fixes |
diff --git a/docs/release.md b/docs/release.md
index d878714..bb9bb92 100644
--- a/docs/release.md
+++ b/docs/release.md
@@ -1,27 +1,58 @@
-# 릴리즈 — 태그를 push 하면 릴리즈 페이지가 생긴다
+# 릴리즈 — 태그를 push 하고, 레인이 빌드한 것으로 릴리즈 페이지를 낸다
-> Owns: How a vX.Y.Z tag becomes a release page, what the workflow attaches, and what stays manual · Index: [docs/README.md](README.md)
+> Owns: How a vX.Y.Z tag becomes a release page, what the lane builds and the publisher attaches, and what stays manual · Index: [docs/README.md](README.md)
-릴리즈 페이지는 손으로 만들지 않는다. `vX.Y.Z` 태그가 push 되면 `.github/workflows/release.yml`
-이 그 태그의 `CHANGELOG.md` 절을 본문으로 페이지를 만든다. 사람이 `gh release create` 를 기억할
-필요가 없게 하는 것이 목적이다 — v2.5.3 이 태그·CHANGELOG·README 까지 올라간 채 릴리즈 페이지만
-빠져서, 릴리즈 목록에는 v2.5.2 가 Latest 로 남아 있었던 적이 있다.
+릴리즈 페이지는 손으로 만들지 않는다. `vX.Y.Z` 태그를 push 한 뒤 `scripts/release_publish.py` 가
+그 태그의 `CHANGELOG.md` 절을 본문으로 페이지를 만든다. 사람이 `gh release create` 의 인자를
+기억할 필요가 없게 하는 것이 목적이다 — v2.5.3 이 태그·CHANGELOG·README 까지 올라간 채 릴리즈
+페이지만 빠져서, 릴리즈 목록에는 v2.5.2 가 Latest 로 남아 있었던 적이 있다.
+
+GitHub-hosted CI(GitHub Actions)는 쓰지 않는다. 테스트 게이트와 wheel·sdist 빌드는 메인테이너의
+리눅스 러너에서 `scripts/linux_lane.sh` 가 돌리고, 페이지를 내는 기계는 아무것도 빌드하지 않고
+레인이 만든 것을 붙인다.
+
+레인이 통과했다는 것은 한 번의 실행이 exit 0 으로 끝났거나, 같은 커밋에서 `--rife-unmeasured "<이유>"`
+실행(exit 3, RIFE 를 재지 못했다고 끝에 적는다)과 `--rife-only` 실행(exit 0)이 둘 다 끝났다는
+뜻이다. RIFE 는 rife-ncnn-vulkan 을 돌릴 수 있는 Vulkan 드라이버가 있어야 잴 수 있다 — WSL1 의 Mesa
+lavapipe 에서는 첫 업로드에서 죽는다 — 그래서 그런 호스트에서는 RIFE 를 떼어 내되 조용히 건너뛰지는
+않는다.
+
+**미결 (2026-10-06)**: GitHub CI 를 걷어낸 뒤로 리눅스 RIFE(`--rife-only`)는 아직 한 번도 재지 못했다 —
+마지막 측정은 v2.35.0 의 CI 다. 진짜 리눅스 커널의 x86-64 호스트가 준비되면 이 변경이 들어간 커밋과
+다음 릴리즈(v2.36.0) 커밋에서 `--rife-only` 를 돌려 채운다. 채우면 이 문단을 지운다.
## 한 묶음
1. **릴리즈 커밋** — `CHANGELOG.md` 의 `## Unreleased (vX.Y.Z)` 절을 `## vX.Y.Z - <제목>` 으로
바꾸고, `pyproject.toml` 의 `version` 과 `SKILL.md` 의 `version:` 을 그 버전으로 맞춘다
(둘의 일치는 `tests/packaging/test_version_ssot.py` 가 강제한다).
-2. **PR 로 `main` 머지** — `main` 은 보호 브랜치라 직접 push 가 거부된다. CI 가 초록이어야 한다.
+2. **PR 로 `main` 머지** — `main` 은 보호 브랜치라 직접 push 가 거부된다. 머지할 커밋에서 리눅스
+ 레인이 통과해야 한다(위 정의) — 러너에서 그 커밋의 깨끗한 클론으로 `scripts/linux_lane.sh`.
3. **태그 push** — 코드네임 접두사 없는 `vX.Y.Z` 로.
```bash
git tag vX.Y.Z && git push origin vX.Y.Z
```
-4. **워크플로가 릴리즈를 만든다** — 태그가 가리키는 커밋에서 wheel·sdist·`SHA256SUMS` 를 빌드하고,
- 그 버전의 CHANGELOG 절을 본문으로, 절이 이름 댄 GIF 를 자산으로 붙여 릴리즈를 생성한다.
-5. **확인은 `gh release view`** — 태그를 push 한 것으로 끝이 아니다. 이게 성공해야 릴리즈가 끝난 것이다.
+4. **러너에서 태그 커밋을 패키징한다** — 태그가 가리키는 커밋의 깨끗한 클론에서, 체크아웃 밖의 빈
+ 디렉터리로.
+
+ ```bash
+ scripts/linux_lane.sh --artifact <빈 디렉터리>
+ ```
+
+ 게이트를 통과한 뒤에만 wheel·sdist·`SHA256SUMS`·`SOURCE_SHA`(그 커밋) 네 파일을 쓴다
+ (`--rife-unmeasured` 와 함께 쓰면 같은 커밋의 `--rife-only` 도 통과해야 레인이 통과한 것이다).
+ 그 디렉터리를 페이지를 낼 기계로 가져온다.
+5. **페이지를 낸다** — 태그가 있는 체크아웃에서.
+
+ ```bash
+ .venv/bin/python scripts/release_publish.py --tag vX.Y.Z --prebuilt <가져온 디렉터리>
+ ```
+
+ `SOURCE_SHA` 가 태그 커밋이고 `SHA256SUMS` 가 두 아카이브와 맞을 때만 붙인다. 그 버전의
+ CHANGELOG 절을 본문으로, 절이 이름 댄 GIF 를 자산으로 함께 붙여 릴리즈를 생성한다.
+6. **확인은 `gh release view`** — 태그를 push 한 것으로 끝이 아니다. 이게 성공해야 릴리즈가 끝난 것이다.
```bash
gh release view vX.Y.Z --repo aldegad/sprite-gen
@@ -29,14 +60,14 @@
## 이미 있는 릴리즈는 건드리지 않는다
-이미 페이지가 있는 태그로 워크플로가 다시 돌면 **아무것도 만들지 않고 아무것도 고치지 않고** 통과한다
-(`… already has a release page …; body and assets left untouched.`). 실패한 잡을 다시 돌려도 공개된
-페이지를 덮어쓰지 않는다는 뜻이고, 반대로 **이미 공개된 페이지의 본문·자산을 워크플로로 고칠 수는 없다**
-— 고칠 일이 생기면 `gh release edit` / `gh release upload` 로 직접 한다.
+이미 페이지가 있는 태그로 스크립트를 다시 돌리면 **아무것도 만들지 않고 아무것도 고치지 않고**
+통과한다(`… already has a release page …; body and assets left untouched.`). 실패한 실행을 다시
+돌려도 공개된 페이지를 덮어쓰지 않는다는 뜻이고, 반대로 **이미 공개된 페이지의 본문·자산을 이
+스크립트로 고칠 수는 없다** — 고칠 일이 생기면 `gh release edit` / `gh release upload` 로 직접 한다.
## 쇼케이스 GIF 는 레포에 커밋된 것만 붙는다
-워크플로가 자산으로 첨부하는 GIF 는 **두 조건을 모두 만족한 것뿐**이다:
+스크립트가 자산으로 첨부하는 GIF 는 **두 조건을 모두 만족한 것뿐**이다:
- 그 버전의 CHANGELOG 절이 `docs/assets/<이름>.gif` 로 이름을 댄다 (본문의 맨 `<이름>.gif` 도
`docs/assets/` 안에 그 파일이 있으면 같은 것으로 본다), **그리고**
@@ -52,34 +83,38 @@ gh release upload vX.Y.Z <clip>.gif --repo aldegad/sprite-gen
본문에서 그 클립을 보여주려면 릴리즈 다운로드 URL
(`https://github.com/aldegad/sprite-gen/releases/download/vX.Y.Z/<clip>.gif`)로 임베드하고,
공개 후 그 URL 이 200 인지 확인한다. 반대로 CHANGELOG 절이 `docs/assets/…` 경로를 이름 댔는데 그
-파일이 체크아웃에 없으면, 죽은 이미지가 달린 페이지를 내보내는 대신 **잡이 실패한다.**
+파일이 체크아웃에 없으면, 죽은 이미지가 달린 페이지를 내보내는 대신 **스크립트가 멈춘다.**
## 태그 없이 미리 돌려보기
-`workflow_dispatch` 로 같은 스크립트를 `--dry-run` 으로 돌릴 수 있다. 태그도, 릴리즈도, 업로드도
-없이 제목·본문·첨부 목록만 잡 요약에 찍는다. 이 경로는 **dispatch 한 ref 의 CHANGELOG** 를 읽는다
-(입력한 태그의 것이 아니라) — 릴리즈 커밋을 준비하는 브랜치에서 본문을 미리 읽어보라는 뜻이다.
-GitHub 은 기본 브랜치에 있는 워크플로만 dispatch 하므로, 이 파일이 `main` 에 들어간 뒤부터 쓸 수 있다.
+`--dry-run` 으로 같은 판정을 돌린다. 태그도, 릴리즈도, 업로드도 없이 제목·본문·첨부 목록만 찍는다.
+`--checkout` 의 `CHANGELOG.md` 를 읽으므로, 릴리즈 커밋을 준비하는 브랜치에서 본문을 미리 읽어 볼 수
+있다. `--prebuilt` 없이 돌리면 그 자리에서 빌드하므로, 빌드하지 않는 기계에서는 `--skip-build`(GIF
+만 붙는 목록)로 판정만 본다.
-## 잡이 빨갛게 죽는 경우
+## 스크립트가 멈추는 경우
전부 "조용히 이상한 페이지" 대신 실패를 고른 지점이다.
- 태그에 해당하는 `## vX.Y.Z` 절이 `CHANGELOG.md` 에 없다 (있는 절 목록을 같이 찍는다).
- 그 절이 비어 있다.
- 절이 이름 댄 `docs/assets/…gif` 가 체크아웃에 없다.
-- 빌드 디렉터리가 비어 있지 않다 — 낡은 아카이브가 이번 릴리즈 자산으로 섞여 올라가는 것을 막는다.
+- `--prebuilt` 디렉터리가 wheel 하나·sdist 하나·`SHA256SUMS`·`SOURCE_SHA` 말고 다른 것을 담고
+ 있거나, 아카이브 버전이 태그와 다르거나, `SOURCE_SHA` 가 태그 커밋이 아니거나, `SHA256SUMS` 가
+ 아카이브와 맞지 않는다 — 다른 커밋의 빌드나 낡은 아카이브가 이번 릴리즈 자산으로 섞이는 것을 막는다.
+- 그 자리에서 빌드할 때 빌드 디렉터리가 비어 있지 않다 — 같은 이유다.
- `gh` 가 "릴리즈가 있다/없다" 를 답하지 못했다 (토큰 없음, 네트워크 끊김, 5xx). **모르는 답은
'없음' 으로 읽지 않는다** — 그대로 멈춘다.
## `release not found` 는 "레포 없음" 이기도 하다
`gh release view` 는 **없는 레포·권한 없는 레포**에 대고 물어도 똑같이 `release not found` 로 답한다.
-"릴리즈가 아직 없다" 와 "레포 이름을 잘못 썼다" 가 같은 문장인 셈이다. 워크플로에서는 `--repo` 가
-`aldegad/sprite-gen` 으로 고정이고 잡 자신의 토큰을 쓰므로 이 모호함에 도달하지 않고, 도달하더라도
-뒤따르는 생성이 크게 실패한다. 손으로 확인할 때만 주의하면 된다 — `--repo` 오타가 "아직 릴리즈가
-없네" 로 읽힌다. `gh` 의 입자도 한계이지 스크립트가 고칠 수 있는 것이 아니다.
+"릴리즈가 아직 없다" 와 "레포 이름을 잘못 썼다" 가 같은 문장인 셈이다. 스크립트의 기본 `--repo` 는
+`aldegad/sprite-gen` 이라 보통은 이 모호함에 도달하지 않고, 도달하더라도 뒤따르는 생성이 크게
+실패한다. `--repo` 를 손으로 줄 때만 주의하면 된다 — 오타가 "아직 릴리즈가 없네" 로 읽힌다. `gh` 의
+입자도 한계이지 스크립트가 고칠 수 있는 것이 아니다.
## Related
- [docs/README.md](README.md) — documentation index
+- `scripts/linux_lane.sh` — the test gates and the release build, on the maintainer's Linux runner
diff --git a/scripts/linux_lane.sh b/scripts/linux_lane.sh
new file mode 100755
index 0000000..643ac69
--- /dev/null
+++ b/scripts/linux_lane.sh
@@ -0,0 +1,178 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+# The test gates, run on the maintainer's own Linux runner. GitHub-hosted CI is not used.
+#
+# What the CI job ran, in the same order: a clean virtual environment installed the way the
+# quickstart does (`pip install -e ".[dev]"`), RIFE installed through the user's own path
+# (`sprite-gen rife install`, its check frame on the host's Vulkan driver), the quickstart smoke
+# (prepare -> extract -> compose) and the whole test suite.
+#
+# Run it from a clean clone of the commit being measured, on x86-64 Linux with:
+# - Python 3.14 (`python3.14` on PATH, or named by SPRITE_GEN_LANE_PYTHON),
+# - ffmpeg, and img2webp from libwebp >= 1.5 (its `-exact` flag),
+# - a Vulkan loader with a CPU driver (Mesa lavapipe is enough).
+# The host's tools are not installed by this script: a missing one ends the run by name. The
+# environment it creates lives in the clone (.venv, ignored), as the quickstart's does.
+#
+# `--artifact <dir>` also packages the commit after the gates passed: the wheel and the sdist
+# built from a second, untouched clone, SHA256SUMS over both, and SOURCE_SHA naming the commit.
+# `scripts/release_publish.py --prebuilt <dir>` attaches exactly that (docs/release.md). <dir>
+# must be outside the checkout and empty.
+#
+# RIFE needs a Vulkan driver that can run rife-ncnn-vulkan. On a host whose driver cannot (Mesa
+# lavapipe under WSL1 crashes in rife-ncnn-vulkan's first upload), the RIFE gates are split off,
+# never passed over in silence:
+# --rife-unmeasured "<why>" every gate but RIFE: no `rife install`, and the suite runs with an
+# empty data directory and no RIFE on PATH, so the tests that need
+# the real binary skip for that stated reason. The run ends by naming
+# what it did not measure and exits 3, not 0.
+# --rife-only the RIFE gates alone, on a host where Vulkan works: `rife install`
+# (its check frame) and tests/video/test_rife.py, none of it skipped.
+# A commit has passed the lane when one run exits 0, or when a `--rife-unmeasured` run (exit 3)
+# and a `--rife-only` run (exit 0) of the same commit both did.
+set -euo pipefail
+
+artifact_dir=""
+rife_unmeasured=""
+rife_only=0
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --artifact)
+ [ $# -ge 2 ] || { echo "linux_lane: --artifact needs a directory" >&2; exit 2; }
+ artifact_dir=$2
+ shift 2
+ ;;
+ --rife-unmeasured)
+ [ $# -ge 2 ] && [ -n "$2" ] || { echo "linux_lane: --rife-unmeasured needs the reason" >&2; exit 2; }
+ rife_unmeasured=$2
+ shift 2
+ ;;
+ --rife-only)
+ rife_only=1
+ shift
+ ;;
+ *)
+ echo "linux_lane: unknown argument $1" >&2
+ exit 2
+ ;;
+ esac
+done
+
+if [ "$rife_only" = 1 ] && { [ -n "$rife_unmeasured" ] || [ -n "$artifact_dir" ]; }; then
+ echo "linux_lane: --rife-only measures RIFE alone; it takes neither --rife-unmeasured nor --artifact" >&2
+ exit 2
+fi
+
+PINNED_PYTHON=3.14
+PYTHON=${SPRITE_GEN_LANE_PYTHON:-python$PINNED_PYTHON}
+
+fail() {
+ echo "linux_lane: $*" >&2
+ exit 1
+}
+step() {
+ echo "== $*"
+}
+
+cd "$(git rev-parse --show-toplevel)"
+root=$(pwd -P)
+
+step "preflight"
+[ "$(uname -s)" = Linux ] || fail "this lane runs on Linux, not $(uname -s)"
+[ "$(uname -m)" = x86_64 ] || fail "this lane runs on x86-64, not $(uname -m)"
+command -v "$PYTHON" >/dev/null || fail "$PYTHON is not on PATH (or set SPRITE_GEN_LANE_PYTHON)"
+case "$("$PYTHON" -c 'import sys; print("%d.%d" % sys.version_info[:2])')" in
+ "$PINNED_PYTHON") ;;
+ *) fail "$PYTHON is $("$PYTHON" --version 2>&1); the lane pins $PINNED_PYTHON" ;;
+esac
+command -v ffmpeg >/dev/null || fail "ffmpeg is not on PATH"
+command -v img2webp >/dev/null || fail "img2webp (libwebp >= 1.5) is not on PATH"
+# img2webp -version exits 1 without an output file; -h is the honest probe. The probes read
+# their whole input (no `grep -q`): under pipefail an early-exiting grep kills the writer with
+# SIGPIPE and the pipeline reads as a failure.
+img2webp -h 2>&1 | grep -- -exact >/dev/null || fail "img2webp has no -exact flag; libwebp must be 1.5 or newer"
+/sbin/ldconfig -p | grep 'libvulkan\.so\.1' >/dev/null || fail "no Vulkan loader (libvulkan.so.1)"
+git diff --quiet && git diff --cached --quiet || fail "the checkout has uncommitted changes"
+[ ! -e .venv ] || fail ".venv already exists; run from a fresh clone"
+if [ -n "$artifact_dir" ]; then
+ mkdir -p "$artifact_dir"
+ artifact_dir=$(cd "$artifact_dir" && pwd -P)
+ case "$artifact_dir/" in
+ "$root/"*) fail "--artifact must be outside the checkout" ;;
+ esac
+ [ -z "$(ls -A "$artifact_dir")" ] || fail "--artifact $artifact_dir is not empty"
+fi
+sha=$(git rev-parse HEAD)
+echo "commit $sha"
+echo "$("$PYTHON" --version), $(ffmpeg -version | head -1 | cut -d' ' -f1-3)"
+
+step "install (clean environment, as the quickstart does)"
+"$PYTHON" -m venv .venv
+.venv/bin/pip install --quiet -e ".[dev]"
+.venv/bin/pip freeze --exclude-editable
+
+if [ "$rife_only" = 1 ]; then
+ step "RIFE (sprite-gen rife install)"
+ .venv/bin/sprite-gen rife install
+ step "RIFE tests (tests/video/test_rife.py, none skipped)"
+ rife_log=$(mktemp)
+ trap 'rm -f "$rife_log"' EXIT
+ .venv/bin/python -m pytest -q -rs tests/video/test_rife.py | tee "$rife_log"
+ ! grep -E '^SKIPPED' "$rife_log" >/dev/null || fail "a RIFE test skipped; this run is meant to measure them"
+ echo "linux_lane: the RIFE gates passed at $sha"
+ exit 0
+fi
+
+if [ -n "$rife_unmeasured" ]; then
+ step "RIFE: not measured on this host ($rife_unmeasured)"
+ # Nowhere the engine looks may hold a RIFE: an empty data directory for the suite, nothing on
+ # PATH, no SPRITE_GEN_RIFE. The real-binary tests then skip for the reason they name.
+ [ -z "${SPRITE_GEN_RIFE:-}" ] || fail "SPRITE_GEN_RIFE is set; --rife-unmeasured runs without RIFE"
+ ! command -v rife-ncnn-vulkan >/dev/null || fail "rife-ncnn-vulkan is on PATH; --rife-unmeasured runs without RIFE"
+ no_rife_data=$(mktemp -d)
+ export XDG_DATA_HOME=$no_rife_data
+else
+ step "RIFE (sprite-gen rife install)"
+ .venv/bin/sprite-gen rife install
+fi
+
+step "quickstart smoke (prepare -> extract -> compose)"
+smoke=$(mktemp -d)
+trap 'rm -rf "$smoke" "${no_rife_data:-}"' EXIT
+.venv/bin/python scripts/prepare_sprite_run.py --help > /dev/null
+cp -r tests/fixtures/run "$smoke/run"
+.venv/bin/python scripts/extract_sprite_row_frames.py --run-dir "$smoke/run"
+.venv/bin/python scripts/compose_sprite_atlas.py --run-dir "$smoke/run"
+test -f "$smoke/run/sprite-sheet-alpha.png"
+test -f "$smoke/run/manifest.json"
+
+step "tests"
+.venv/bin/python -m pytest -q
+
+if [ -n "$rife_unmeasured" ]; then
+ echo "linux_lane: every gate but RIFE passed at $sha"
+ echo "linux_lane: RIFE NOT MEASURED here ($rife_unmeasured): run \`scripts/linux_lane.sh --rife-only\` at $sha on a host where Vulkan works"
+else
+ echo "linux_lane: every gate passed at $sha"
+fi
+
+if [ -n "$artifact_dir" ]; then
+ step "package"
+ # From a second clone of the same commit, so nothing the gates wrote (.venv, egg-info, run
+ # outputs) can reach the archives.
+ pkg=$(mktemp -d)
+ trap 'rm -rf "$smoke" "$pkg" "${no_rife_data:-}"' EXIT
+ git clone -q --no-hardlinks . "$pkg/src"
+ git -C "$pkg/src" checkout -q "$sha"
+ .venv/bin/pip install --quiet build
+ (cd "$pkg/src" && "$root/.venv/bin/python" -m build --outdir "$artifact_dir" > "$pkg/build.log" 2>&1) ||
+ { tail -20 "$pkg/build.log" >&2; fail "python -m build failed"; }
+ (cd "$artifact_dir" && sha256sum -- *.whl *.tar.gz > SHA256SUMS)
+ echo "$sha" > "$artifact_dir/SOURCE_SHA"
+ ls -l "$artifact_dir"
+ cat "$artifact_dir/SHA256SUMS"
+fi
+
+if [ -n "$rife_unmeasured" ]; then
+ exit 3
+fi
diff --git a/scripts/release_notes.py b/scripts/release_notes.py
index 13b639e..bf3411d 100644
--- a/scripts/release_notes.py
+++ b/scripts/release_notes.py
@@ -1,7 +1,7 @@
# SPDX-License-Identifier: Apache-2.0
"""Render the GitHub release body for one tag out of `CHANGELOG.md`.
-`.github/workflows/release.yml` calls this when a `v*` tag is pushed, so the release
+`scripts/release_publish.py` calls this after a `v*` tag is pushed, so the release
page is built from the file that already describes the release instead of from whatever
the person cutting the tag remembers to paste. A tag with no `## vX.Y.Z` section — or a
section with no content — is a failure here, not an empty release page.
diff --git a/scripts/release_publish.py b/scripts/release_publish.py
index 4646aa4..a1e41b6 100644
--- a/scripts/release_publish.py
+++ b/scripts/release_publish.py
@@ -2,9 +2,11 @@
"""Publish the GitHub release page for a tag, or rehearse it without touching anything.
The gate this closes: a `vX.Y.Z` tag can be pushed, changelogged and announced while the
-release page is never created, leaving an older version as Latest. `.github/workflows/
-release.yml` runs this on every `v*` tag push, and the same file runs it with `--dry-run`
-on `workflow_dispatch` so the decision path can be rehearsed on a branch.
+release page is never created, leaving an older version as Latest. The release chain runs this
+right after the tag is pushed (docs/release.md), and `--dry-run` rehearses the same decision on
+a branch. GitHub-hosted CI is not used: the wheel and sdist come from the Linux lane
+(`scripts/linux_lane.sh --artifact <dir>`, on the maintainer's runner) and are attached with
+`--prebuilt <dir>`, so the machine that publishes builds nothing.
Three outcomes, and no fourth:
@@ -18,15 +20,15 @@ Three outcomes, and no fourth:
other failure (no token, no network, a 5xx) stops the run instead of being read as "not
there yet" and answered with a create.
-Standard library only, same as `release_notes.py`; `gh` and `python -m build` are the
+Standard library only, same as `release_notes.py`; `gh`, `git` and `python -m build` are the
only external commands.
.venv/bin/python scripts/release_publish.py --tag v2.5.3 --dry-run
+ .venv/bin/python scripts/release_publish.py --tag v2.5.3 --prebuilt <lane artifact dir>
"""
from __future__ import annotations
import argparse
-import os
import subprocess
import sys
import tempfile
@@ -93,11 +95,44 @@ def checksum_distribution(dist_dir: Path) -> list[Path]:
return [*archives, sums]
-def _emit(text: str, summary_path: str | None) -> None:
- print(text)
- if summary_path:
- with open(summary_path, "a", encoding="utf-8") as handle:
- handle.write(text + "\n")
+def take_prebuilt(prebuilt: Path, tag: str, *, cwd: Path) -> list[Path]:
+ """The wheel, sdist and SHA256SUMS a lane built for this tag's commit — checked, not rebuilt.
+
+ Nothing is attached unless the directory holds exactly one wheel and one sdist of the
+ tag's version plus SHA256SUMS and SOURCE_SHA, SHA256SUMS matches both archives, and
+ SOURCE_SHA names the commit the tag points to in this checkout. A build of another commit,
+ a stray file or a changed archive stops the release instead of riding along.
+ """
+ import hashlib
+
+ version = release_notes.version_of(tag)
+ if not prebuilt.is_dir():
+ raise PublishError(f"{prebuilt} is not a directory")
+ names = sorted(p.name for p in prebuilt.iterdir())
+ wheels = [n for n in names if n.endswith(".whl")]
+ sdists = [n for n in names if n.endswith(".tar.gz")]
+ if len(wheels) != 1 or len(sdists) != 1 or set(names) != {*wheels, *sdists, "SHA256SUMS", "SOURCE_SHA"}:
+ raise PublishError(
+ f"{prebuilt} must hold exactly one wheel, one sdist, SHA256SUMS and SOURCE_SHA; "
+ f"it holds {names}")
+ wheel, sdist = wheels[0], sdists[0]
+ if f"-{version}-" not in wheel or not sdist.endswith(f"-{version}.tar.gz"):
+ raise PublishError(f"{wheel} and {sdist} are not version {version}")
+ proc = _run(["git", "rev-parse", "--verify", "--quiet", f"{tag}^{{commit}}"], cwd=cwd)
+ if proc.returncode != 0:
+ raise PublishError(f"{tag} is not a tag in {cwd}; tag the release commit first")
+ tag_commit = proc.stdout.strip()
+ source = (prebuilt / "SOURCE_SHA").read_text(encoding="utf-8").strip()
+ if source != tag_commit:
+ raise PublishError(f"{prebuilt} was built from {source or '(nothing)'}, but {tag} is {tag_commit}")
+ listed = {}
+ for line in (prebuilt / "SHA256SUMS").read_text(encoding="utf-8").splitlines():
+ digest, _, name = line.partition(" ")
+ listed[name] = digest
+ actual = {n: hashlib.sha256((prebuilt / n).read_bytes()).hexdigest() for n in (wheel, sdist)}
+ if listed != actual:
+ raise PublishError(f"SHA256SUMS in {prebuilt} does not match its archives")
+ return [prebuilt / wheel, prebuilt / sdist, prebuilt / "SHA256SUMS"]
def main(argv: list[str] | None = None) -> int:
@@ -114,10 +149,16 @@ def main(argv: list[str] | None = None) -> int:
help="where the wheel and sdist go (default: <checkout>/dist)")
parser.add_argument("--skip-build", action="store_true",
help="attach only the GIFs; for rehearsing the decision alone")
+ parser.add_argument("--prebuilt", type=Path, default=None,
+ help="attach the wheel, sdist and SHA256SUMS that "
+ "`scripts/linux_lane.sh --artifact` built for the tag's commit "
+ "instead of building here")
parser.add_argument("--gh", default="gh", help="the gh executable to call")
args = parser.parse_args(argv)
+ if args.prebuilt is not None and (args.skip_build or args.dist_dir is not None):
+ parser.error("--prebuilt takes the place of a build here; "
+ "it does not combine with --skip-build or --dist-dir")
- summary = os.environ.get("GITHUB_STEP_SUMMARY")
checkout = args.checkout.resolve()
dist_dir = (args.dist_dir or checkout / "dist").resolve()
@@ -130,24 +171,25 @@ def main(argv: list[str] | None = None) -> int:
branch=args.branch,
)
if release_exists(args.gh, args.tag, repo=args.repo, cwd=checkout):
- _emit(f"{args.tag} already has a release page on {args.repo}; "
- f"body and assets left untouched.", summary)
+ print(f"{args.tag} already has a release page on {args.repo}; "
+ f"body and assets left untouched.")
return 0
assets = [str(checkout / rel) for rel in page["assets"]]
if args.skip_build:
built: list[Path] = []
+ elif args.prebuilt is not None:
+ built = take_prebuilt(args.prebuilt.resolve(), args.tag, cwd=checkout)
else:
built = build_distribution(dist_dir, cwd=checkout)
assets = [str(p) for p in built] + assets
if args.dry_run:
listing = "\n".join(f" {a}" for a in assets) or " (none)"
- _emit(
+ print(
f"DRY RUN — {args.tag} has no release page on {args.repo}. Would create:\n"
f"\ntitle: {page['title']}\n\nassets:\n{listing}\n\nbody:\n{'-' * 60}\n"
- f"{page['body']}\n{'-' * 60}\n\nNothing was created, uploaded or tagged.",
- summary,
+ f"{page['body']}\n{'-' * 60}\n\nNothing was created, uploaded or tagged."
)
return 0
@@ -161,7 +203,7 @@ def main(argv: list[str] | None = None) -> int:
raise PublishError(f"gh release create failed:\n{(proc.stderr or proc.stdout).strip()}")
if not release_exists(args.gh, args.tag, repo=args.repo, cwd=checkout):
raise PublishError(f"gh release create reported success but {args.tag} has no page")
- _emit(f"published {args.repo} {args.tag}: {proc.stdout.strip()}", summary)
+ print(f"published {args.repo} {args.tag}: {proc.stdout.strip()}")
return 0
except (release_notes.ReleaseNotesError, PublishError, OSError) as exc:
print(f"release_publish: {exc}", file=sys.stderr)
diff --git a/tests/packaging/test_project_metadata.py b/tests/packaging/test_project_metadata.py
index dc2f605..8e978df 100644
--- a/tests/packaging/test_project_metadata.py
+++ b/tests/packaging/test_project_metadata.py
@@ -20,14 +20,13 @@ def _version_tuple(version: str) -> tuple[int, int]:
def _ci_python_versions() -> list[str]:
- workflow = (ROOT / ".github" / "workflows" / "ci.yml").read_text(encoding="utf-8")
+ """The Python the gates run on: the Linux lane's pin (GitHub-hosted CI is not used)."""
+ lane = (ROOT / "scripts" / "linux_lane.sh").read_text(encoding="utf-8")
- matrix = re.search(r"python-version:\s*\[(?P<versions>[^\]]+)\]", workflow)
- assert matrix, "CI must declare the setup-python matrix on one line"
- versions = re.findall(r'"(\d+\.\d+)"', matrix.group("versions"))
- assert versions, "CI Python matrix must include at least one version"
+ pinned = re.findall(r"^PINNED_PYTHON=(\d+\.\d+)$", lane, re.MULTILINE)
+ assert pinned, "the lane must pin its Python on a PINNED_PYTHON=<major>.<minor> line"
- return versions
+ return pinned
def test_ci_versions_are_supported_and_documented() -> None:
diff --git a/tests/release/test_release_publish.py b/tests/release/test_release_publish.py
index bfda62a..372bd1a 100644
--- a/tests/release/test_release_publish.py
+++ b/tests/release/test_release_publish.py
@@ -1,5 +1,5 @@
# SPDX-License-Identifier: Apache-2.0
-"""The release workflow's decision: publish once, never twice, never on a guess.
+"""The release publisher's decision: publish once, never twice, never on a guess.
`gh` is replaced by a stub that records every call and keeps its "is there a release?"
answer in a file, so a second run sees exactly what a real re-run would see. Fixtures are
@@ -171,3 +171,89 @@ def test_a_dist_directory_with_stale_archives_is_refused(harness: Harness, tmp_p
assert proc.returncode == 2
assert "not empty" in proc.stderr
assert not harness.published()
+
+
+def _git(cwd: Path, *args: str) -> str:
+ return subprocess.run(
+ ["git", "-c", "user.name=t", "-c", "[email protected]", *args],
+ cwd=cwd, check=True, capture_output=True, text=True).stdout.strip()
+
+
+def _tagged(harness: Harness) -> str:
+ """Make the throwaway checkout a repository whose v1.3.0 tag is its only commit."""
+ _git(harness.checkout, "init", "-q")
+ _git(harness.checkout, "add", "-A")
+ _git(harness.checkout, "commit", "-q", "-m", "release")
+ _git(harness.checkout, "tag", "v1.3.0")
+ return _git(harness.checkout, "rev-parse", "HEAD")
+
+
+def _lane_artifact(directory: Path, source_sha: str) -> Path:
+ """What `scripts/linux_lane.sh --artifact` leaves: a wheel, an sdist, SHA256SUMS, SOURCE_SHA."""
+ import hashlib
+
+ directory.mkdir()
+ lines = []
+ for name, body in (("sprite_gen-1.3.0-py3-none-any.whl", b"wheel"),
+ ("sprite_gen-1.3.0.tar.gz", b"sdist")):
+ (directory / name).write_bytes(body)
+ lines.append(f"{hashlib.sha256(body).hexdigest()} {name}\n")
+ (directory / "SHA256SUMS").write_text("".join(lines), encoding="utf-8")
+ (directory / "SOURCE_SHA").write_text(source_sha + "\n", encoding="utf-8")
+ return directory
+
+
+def _run_prebuilt(harness: Harness, prebuilt: Path, *args: str) -> subprocess.CompletedProcess[str]:
+ return subprocess.run(
+ [sys.executable, str(PUBLISH), "--tag", "v1.3.0", "--repo", "example/example",
+ "--checkout", str(harness.checkout), "--gh", str(harness.gh), "--prebuilt", str(prebuilt),
+ *args],
+ capture_output=True, text=True,
+ env={**os.environ, "GH_STUB_STATE": str(harness.state), "GH_STUB_LOG": str(harness.log)})
+
+
+def test_a_lane_build_of_the_tag_commit_is_attached_without_building(harness: Harness, tmp_path: Path) -> None:
+ prebuilt = _lane_artifact(tmp_path / "lane", _tagged(harness))
+ proc = _run_prebuilt(harness, prebuilt)
+ assert proc.returncode == 0, proc.stderr
+ created = [c for c in harness.calls if c.startswith("release create")]
+ assert len(created) == 1, harness.calls
+ for name in ("sprite_gen-1.3.0-py3-none-any.whl", "sprite_gen-1.3.0.tar.gz", "SHA256SUMS", "wave-cube.gif"):
+ assert name in created[0], name
+ assert not (harness.checkout / "dist").exists(), "nothing is built where the release is published"
+
+
+def test_a_lane_build_of_another_commit_is_refused(harness: Harness, tmp_path: Path) -> None:
+ _tagged(harness)
+ prebuilt = _lane_artifact(tmp_path / "lane", "0" * 40)
+ proc = _run_prebuilt(harness, prebuilt)
+ assert proc.returncode == 2
+ assert "was built from" in proc.stderr
+ assert not harness.published()
+
+
+def test_a_lane_build_whose_archive_changed_is_refused(harness: Harness, tmp_path: Path) -> None:
+ prebuilt = _lane_artifact(tmp_path / "lane", _tagged(harness))
+ (prebuilt / "sprite_gen-1.3.0.tar.gz").write_bytes(b"sdist, changed after the lane")
+ proc = _run_prebuilt(harness, prebuilt)
+ assert proc.returncode == 2
+ assert "does not match" in proc.stderr
+ assert not harness.published()
+
+
+def test_a_lane_artifact_with_a_stray_file_is_refused(harness: Harness, tmp_path: Path) -> None:
+ """Everything in the directory would be attached, so it must hold exactly the lane's four files."""
+ prebuilt = _lane_artifact(tmp_path / "lane", _tagged(harness))
+ (prebuilt / "sprite_gen-0.0.1-py3-none-any.whl").write_bytes(b"stale")
+ proc = _run_prebuilt(harness, prebuilt)
+ assert proc.returncode == 2
+ assert "exactly one wheel" in proc.stderr
+ assert not harness.published()
+
+
+def test_prebuilt_does_not_combine_with_a_build_here(harness: Harness, tmp_path: Path) -> None:
+ prebuilt = _lane_artifact(tmp_path / "lane", _tagged(harness))
+ proc = _run_prebuilt(harness, prebuilt, "--skip-build")
+ assert proc.returncode == 2
+ assert "--prebuilt" in proc.stderr
+ assert harness.calls == []