Skip to content

Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.

ci(release): resolve the next version ourselves; a chore-only merge really releases nothing (#150)

Shogo Kajiyama6f431f55d130
diff --git a/.github/release-drafter.yml b/.github/release-drafter.yml
index 4c7ed87..8955bc0 100644
--- a/.github/release-drafter.yml
+++ b/.github/release-drafter.yml
@@ -1,25 +1,21 @@
-# Config for release-drafter/release-drafter, used three ways:
+# Config for release-drafter/release-drafter, used two ways:
# - release-drafter.yml (the workflow) runs it live on every push to main, keeping a running
# DRAFT release as a human-readable cross-check -- this draft is never auto-published.
-# - release-drafter.yml *also* runs it on every PR open/reopen/sync, purely for `autolabeler`
-# below -- it applies fix/feature/chore labels to the PR itself from its title/files, so a
-# PR that merges without anyone manually labeling it still carries a real signal instead of
-# silently defaulting to patch every time.
-# - release.yml runs it with dry-run: true to resolve the *actual* next version (via
-# version-resolver below) whenever nobody bumped package.json by hand, then bumps the
-# version and writes CHANGELOG.md itself and releases for real. So the labels below (whether
-# autolabeler applied them or a human did, and "default: patch" for anything still unlabeled)
-# now drive real releases, not just this draft.
+# - release-drafter.yml *also* runs the autolabeler on every PR open/reopen/sync -- it applies
+# fix/feature/chore labels to the PR itself from its title/files, so a PR that merges without
+# anyone manually labeling it still carries a real signal.
#
-# Two rules learned the hard way (2026-09-11, versions 1.0.0-1.0.2 published by accident):
+# release.yml does NOT call release-drafter any more. It resolves the real next version with
+# .github/scripts/resolve_version.py, which reads the same labels the autolabeler applies. Keep
+# the label vocabulary here and there in step. Two things learned the hard way (2026-09-11):
# - `major` is NEVER applied automatically. An earlier autolabeler rule matched the literal
# breaking-change marker anywhere in a PR body; Dependabot PR bodies quote the upstream
# project's release notes, one of which contained it, and three routine dependency bumps
-# became 1.0.0, 1.0.1 and 1.0.2 on npm. A major bump is a deliberate, hand-applied label on a
-# PR someone has read -- and release.yml refuses to auto-bump across a major boundary anyway.
-# - `exclude-labels` keeps chore/ci/docs/dependency PRs out of version resolution entirely, so
-# a merge that changes no shipped file resolves to the *same* version as the last tag and
-# release.yml's guard makes it a no-op. Add `fix`/`feature`/`patch` by hand to override.
+# became 1.0.0, 1.0.1 and 1.0.2 on npm. resolve_version.py refuses a major outright.
+# - `exclude-labels` below only hides chore/ci/docs/dependency PRs from the DRAFT NOTES. It does
+# not make the version resolver say "nothing": `default: patch` still bumps, which is how
+# 1.0.4 shipped for a workflow-only merge. The real "release nothing" decision is
+# resolve_version.py's, not this file's.
name-template: "v$RESOLVED_VERSION"
tag-template: "v$RESOLVED_VERSION"
exclude-labels:
diff --git a/.github/scripts/resolve_version.py b/.github/scripts/resolve_version.py
new file mode 100644
index 0000000..556b727
--- /dev/null
+++ b/.github/scripts/resolve_version.py
@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""Decide the next release version from the labels of the PRs merged since the last tag.
+
+Used by .github/workflows/release.yml. Replaces the earlier release-drafter "dry-run" call,
+which (a) was not a dry run at all -- `dry-run` is not an input of release-drafter v6, the
+warning was ignored, and the step rewrote the draft release on every run -- and (b) could
+never say "nothing to release": release-drafter's `exclude-labels` only hides PRs from the
+notes, the version resolver still applies `default: patch`, so a merge of nothing but chore
+PRs resolved to last+patch and 1.0.4 was published for a workflow-only change (2026-09-11).
+
+Rules (same label vocabulary as .github/release-drafter.yml, so the autolabeler and a human
+reading the PR see the same thing):
+
+ major -> refuse (exit 2): a major is a hand edit of package.json
+ minor / feature / enhancement -> minor
+ patch / fix / bug -> patch
+ only chore / ci / docs / dependencies (or any other label) -> not releasable
+ no label at all -> patch (a PR nobody labelled still ships)
+
+A PR with `chore` AND `fix` is a fix. A commit on main that came from no PR is treated as
+patch unless its subject starts with chore/ci/docs/build (the autolabeler's own title rules).
+If nothing since the last tag is releasable, the resolved version is empty and release.yml
+does nothing.
+
+Pure logic lives in resolve(); the CLI wraps it with `git log` and `gh api`.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+from typing import Callable, Dict, Iterable, List, Optional, Tuple
+
+MAJOR = {"major"}
+MINOR = {"minor", "feature", "enhancement"}
+PATCH = {"patch", "fix", "bug"}
+NOT_RELEASABLE_TITLE = re.compile(r"^(chore|ci|docs|build)\b", re.I)
+PR_NUMBER = re.compile(r"\(#(\d+)\)\s*$")
+
+
+def bump_for_labels(labels: Iterable[str]) -> Optional[str]:
+ """'major' / 'minor' / 'patch' / None (not releasable) for one PR's labels."""
+ names = {l.lower() for l in labels}
+ if names & MAJOR:
+ return "major"
+ if names & MINOR:
+ return "minor"
+ if names & PATCH:
+ return "patch"
+ if not names:
+ return "patch"
+ return None
+
+
+def resolve(last_version: str, subjects: List[str],
+ labels_for: Callable[[int], List[str]]) -> Tuple[Optional[str], List[Dict[str, object]]]:
+ """Return (next_version or None, per-commit decisions).
+
+ subjects: commit subjects on main since the last tag, newest first (git log order).
+ labels_for: PR number -> its label names.
+ """
+ decisions: List[Dict[str, object]] = []
+ bumps: List[str] = []
+ for subject in subjects:
+ m = PR_NUMBER.search(subject)
+ if m:
+ number = int(m.group(1))
+ labels = labels_for(number)
+ bump = bump_for_labels(labels)
+ decisions.append({"subject": subject, "pr": number, "labels": sorted(labels), "bump": bump})
+ else:
+ bump = None if NOT_RELEASABLE_TITLE.match(subject) else "patch"
+ decisions.append({"subject": subject, "pr": None, "labels": [], "bump": bump})
+ if bump:
+ bumps.append(bump)
+ if not bumps:
+ return None, decisions
+ if "major" in bumps:
+ raise SystemExit(
+ "refusing to resolve a major version automatically; a major release is a deliberate, "
+ "hand-made package.json bump in a PR (see docs/contract.md, Stability guarantee)")
+ parts = [int(p) for p in last_version.split(".")]
+ while len(parts) < 3:
+ parts.append(0)
+ major, minor, patch = parts[:3]
+ if "minor" in bumps:
+ return f"{major}.{minor + 1}.0", decisions
+ return f"{major}.{minor}.{patch + 1}", decisions
+
+
+def _gh_labels(repo: str) -> Callable[[int], List[str]]:
+ def labels_for(number: int) -> List[str]:
+ out = subprocess.run(
+ ["gh", "api", f"repos/{repo}/pulls/{number}", "--jq", "[.labels[].name]"],
+ capture_output=True, text=True, check=True).stdout
+ return list(json.loads(out or "[]"))
+ return labels_for
+
+
+def main() -> int:
+ last = os.environ["LAST_VERSION"]
+ repo = os.environ["GITHUB_REPOSITORY"]
+ rev_range = f"v{last}..HEAD" if last != "0.0.0" else "HEAD"
+ subjects = [s for s in subprocess.run(
+ ["git", "log", rev_range, "--format=%s"], capture_output=True, text=True, check=True
+ ).stdout.splitlines() if s.strip()]
+ version, decisions = resolve(last, subjects, _gh_labels(repo))
+ for d in decisions:
+ tag = d["bump"] or "-"
+ print(f" {tag:6} {'#' + str(d['pr']) if d['pr'] else '(no PR)':8} {','.join(d['labels']) or '(unlabeled)':30} {d['subject']}")
+ print(f"last tag v{last} -> {'no release' if version is None else version}")
+ with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as fh:
+ fh.write(f"resolved_version={version or ''}\n")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/.github/workflows/release-drafter.yml b/.github/workflows/release-drafter.yml
index 3d99822..cdfc3fe 100644
--- a/.github/workflows/release-drafter.yml
+++ b/.github/workflows/release-drafter.yml
@@ -1,12 +1,12 @@
# Two jobs sharing one release-drafter config (.github/release-drafter.yml):
# - update_release_draft (push to main): keeps a running DRAFT GitHub Release up to date with
# merged-PR summaries -- a human-readable cross-check against CHANGELOG.md, never published
-# itself. release.yml is the one that actually decides and cuts a release (it uses this same
-# config via its own dry-run call); it doesn't read this draft.
+# itself. release.yml is the one that actually decides and cuts a release (with
+# .github/scripts/resolve_version.py, reading the same labels); it doesn't read this draft.
# - autolabel (PR opened/reopened/synchronized): applies release-drafter's `autolabeler` rules
-# (fix/feature/major/chore, from the PR's title and changed files) to the PR itself, so most
+# (fix/feature/chore, from the PR's title and changed files) to the PR itself, so most
# PRs carry a real label before they merge instead of silently defaulting to patch every time
-# in release.yml's version-resolver. pull_request_target (not pull_request) so a label can
+# in release.yml's version resolution. pull_request_target (not pull_request) so a label can
# still be applied on a PR from a fork, which only ever gets a GITHUB_TOKEN under this trigger.
#
# push-to-main only for the draft-release job, deliberately: release-drafter reads its config from
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 44cadb3..f6dad7d 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -6,10 +6,11 @@ name: release
# anymore, PR merges are the only input:
#
# - If package.json's version still matches the latest release tag (the
-# normal case -- nobody touched it in the merged PR), this job asks
-# release-drafter to resolve the next version from the labels on every PR
-# merged since that tag (same major/minor/patch rules as
-# .github/release-drafter.yml; an unlabeled PR defaults to patch), bumps
+# normal case -- nobody touched it in the merged PR), this job resolves the
+# next version from the labels on every PR merged since that tag
+# (.github/scripts/resolve_version.py: minor/feature/enhancement -> minor,
+# patch/fix/bug -> patch, unlabeled -> patch, chore/ci/docs/dependencies
+# only -> nothing to release, major -> refused), bumps
# package.json and docs/contract.md to that version, writes a CHANGELOG.md
# section listing those merged PRs, and pushes that bump commit to main
# itself before continuing -- see "Auto-bump" below.
@@ -48,7 +49,7 @@ concurrency:
permissions:
contents: write
- pull-requests: read # release-drafter reads merged PRs' labels to resolve the next version
+ pull-requests: read # resolve_version.py reads merged PRs' labels through gh api
id-token: write # required for `npm publish --provenance`
jobs:
@@ -74,20 +75,23 @@ jobs:
echo "needs_auto_bump=false" >> "$GITHUB_OUTPUT"
fi
- # Computes (but does not publish or tag) the next version from the labels on every
- # PR merged since the last vX.Y.Z tag, using the same rules as release-drafter.yml /
- # release-drafter.yml's own always-on draft release. dry-run: true makes this call
- # read-only.
+ # Decides the next version from the labels of every PR merged since the last vX.Y.Z tag
+ # (.github/scripts/resolve_version.py: the same label vocabulary as release-drafter.yml's
+ # autolabeler; chore/ci/docs/dependencies-only PRs are not releasable; an empty result
+ # means "nothing to release" and every remaining step is skipped). This used to be a
+ # release-drafter call with `dry-run: true` -- an input that action does not have, so it
+ # silently ran live, and it could never answer "nothing" (its `exclude-labels` hides PRs
+ # from the notes but `default: patch` still bumps), which published 1.0.4 for a
+ # workflow-only merge. Reads labels through `gh api`, never PR text.
- name: Resolve the next version from merged PR labels
id: drafter
if: steps.setup.outputs.needs_auto_bump == 'true'
- uses: release-drafter/release-drafter@v6
- with:
- dry-run: true
env:
- GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ LAST_VERSION: ${{ steps.setup.outputs.last_version }}
+ run: python3 .github/scripts/resolve_version.py
- # Nobody bumped package.json by hand, and release-drafter found something new to
+ # Nobody bumped package.json by hand, and resolve_version.py found something new to
# release: bump package.json/docs/contract.md ourselves and write a CHANGELOG.md
# section listing the merged PRs (and any issues they closed) since the last tag,
# then push that commit to main before the rest of this job continues. Reads PR
diff --git a/README.md b/README.md
index 07bbaba..22ef0ba 100644
--- a/README.md
+++ b/README.md
@@ -395,7 +395,7 @@ CI (`.github/workflows/ci.yml`) runs on every pull request and on pushes to `mai
`tests/test_contract.py` runs on all three OSes, but a handful of its tests build a fake `ffmpeg` as a `#!/bin/sh` script on a PATH shim to force specific FFmpeg 6/7/8/9 fixture layouts through `doctor`'s parser — that technique isn't portable to Windows, so `test_dry_run_never_runs_ffmpeg_and_writes_nothing` and the whole `DoctorDetectionTests` class (fixture-driven layout parsing) are individually `skipIf`'d there and show as `skipped`, not silently absent, in the Windows job's log. Everything else — contract schema, `reencodes_*`, `doctor.tools`, MCP derivation, and every tool exercised through the contract, including `cut.py`'s provenance fields — runs against the real Windows `ffmpeg` on every PR. See [references/ci-platform-pitfalls.md](references/ci-platform-pitfalls.md) for this and other per-OS behaviour differences already diagnosed, before spending a CI cycle re-diagnosing a platform-only failure.
-**Releasing** is fully automated end to end, including the version number itself — a PR doesn't need to touch `package.json`, `docs/contract.md`, or `CHANGELOG.md` at all. Once a PR merges to `main`, `.github/workflows/release.yml` takes it from there: if nobody bumped the version by hand, it asks [release-drafter](.github/release-drafter.yml) to resolve the next version from the labels on every PR merged since the last tag (`minor`/`feature`/`enhancement` → minor, `fix`/`bug`/`patch` → patch, an unlabeled PR defaults to `patch`; PRs labelled `chore`, `ci`, `docs` or `dependencies` are excluded, so a merge that changes no shipped file releases nothing). Most PRs don't need a label added by hand: `release-drafter.yml`'s `autolabel` job applies one automatically from the PR's title/changed files (`Fix ...` → `fix`, `Add ...`/`feat ...` → `feature`, `docs`/`.md`/`.github/`/`build(deps)` changes → `chore`) as soon as it's opened — add a label yourself only to override that. **A major version is never chosen automatically**: no label rule produces `major`, and the workflow refuses to auto-bump across a major boundary even if someone applies that label — a real major release is a deliberate `package.json` bump in a PR, which the manual path below already handles. It bumps `package.json` and `docs/contract.md`, writes a `CHANGELOG.md` section listing those PRs (and any issues they closed), and pushes that commit to `main` itself. Either way — auto-bumped or hand-bumped in the PR — it then creates the `vX.Y.Z` tag, publishes a GitHub Release with notes extracted from `CHANGELOG.md`'s matching section, and publishes the package to npm. A PR that still wants to write its own version bump and `CHANGELOG.md` prose (e.g. to explain the "why" of a release by hand) can — the automation only fills in when nobody made that call already. A push to `main` with nothing new to release is a no-op. npm publishing needs an `NPM_TOKEN` repo secret (an npm access token with publish rights on this package) — without it the tag and GitHub Release still happen, only the npm step is skipped. A repo that depends on this one (an editing skill, an agent) should pin an `ffmpeg-skill` version by tag or npm version, not by tracking `main` — a merged-but-not-yet-released commit on `main` can be ahead of the last published npm version for the few minutes between merge and this workflow completing.
+**Releasing** is fully automated end to end, including the version number itself — a PR doesn't need to touch `package.json`, `docs/contract.md`, or `CHANGELOG.md` at all. Once a PR merges to `main`, `.github/workflows/release.yml` takes it from there: if nobody bumped the version by hand, it resolves the next version ([.github/scripts/resolve_version.py](.github/scripts/resolve_version.py)) from the labels on every PR merged since the last tag (`minor`/`feature`/`enhancement` → minor, `fix`/`bug`/`patch` → patch, an unlabeled PR defaults to `patch`; a PR whose only labels are `chore`, `ci`, `docs` or `dependencies` is not releasable, so a merge that changes no shipped file releases nothing). Most PRs don't need a label added by hand: `release-drafter.yml`'s `autolabel` job applies one automatically from the PR's title/changed files (`Fix ...` → `fix`, `Add ...`/`feat ...` → `feature`, `docs`/`.md`/`.github/`/`build(deps)` changes → `chore`) as soon as it's opened — add a label yourself only to override that. **A major version is never chosen automatically**: no label rule produces `major`, and the workflow refuses to auto-bump across a major boundary even if someone applies that label — a real major release is a deliberate `package.json` bump in a PR, which the manual path below already handles. It bumps `package.json` and `docs/contract.md`, writes a `CHANGELOG.md` section listing those PRs (and any issues they closed), and pushes that commit to `main` itself. Either way — auto-bumped or hand-bumped in the PR — it then creates the `vX.Y.Z` tag, publishes a GitHub Release with notes extracted from `CHANGELOG.md`'s matching section, and publishes the package to npm. A PR that still wants to write its own version bump and `CHANGELOG.md` prose (e.g. to explain the "why" of a release by hand) can — the automation only fills in when nobody made that call already. A push to `main` with nothing new to release is a no-op. npm publishing needs an `NPM_TOKEN` repo secret (an npm access token with publish rights on this package) — without it the tag and GitHub Release still happen, only the npm step is skipped. A repo that depends on this one (an editing skill, an agent) should pin an `ffmpeg-skill` version by tag or npm version, not by tracking `main` — a merged-but-not-yet-released commit on `main` can be ahead of the last published npm version for the few minutes between merge and this workflow completing.
Contributing a change: see [CONTRIBUTING.md](CONTRIBUTING.md).
diff --git a/references/process-pitfalls.md b/references/process-pitfalls.md
index 3fa7d1b..b600162 100644
--- a/references/process-pitfalls.md
+++ b/references/process-pitfalls.md
@@ -131,3 +131,30 @@ applied, or on files changed, and make the irreversible step refuse anything sur
than assume the surprise was intended. And after wiring any such automation, watch the first
few real runs' *results* (npm, tags) rather than their exit codes: the three runs here were
"success" by every check the job had.
+
+## An action input that does not exist is a warning, not an error -- and "excluded from the notes" is not "no release"
+
+The fix for the accidental majors above (#145) still released **1.0.4** for its own,
+workflow-only merge. Two assumptions in `release.yml` were wrong and nothing checked either:
+
+- `release-drafter/release-drafter@v6` was called with `dry-run: true` to "compute the next
+ version read-only". That action has no `dry-run` input. GitHub Actions logs
+ `Unexpected input(s) 'dry-run'` as a *warning* and runs the step anyway -- so every release
+ run had been rewriting the draft release live, and the "read-only" in the comment was fiction.
+- `exclude-labels` in `release-drafter.yml` was expected to make a chore-only merge resolve to
+ the same version as the last tag. It only removes those PRs from the draft *notes*; the
+ version resolver still applies `default: patch` and reports last+patch. The workflow's "same
+ version → no-op" guard therefore never fired.
+
+Both were visible in the first run's log and in the action's documented inputs, and both were
+missed because the PR's test plan verified the YAML *parsed* and the config *contained* the
+intended keys -- not that the action *did* what the comment claimed. Fixed by taking the
+decision away from the action: `.github/scripts/resolve_version.py` reads the merged PRs'
+labels through `gh api`, returns nothing when nothing is releasable, refuses `major`, and has
+a unit test in `tests/test_contract.py` with fake label data for each rule.
+
+The general rule, twice over now: when wiring a third-party action, read its `action.yml`
+inputs (or `Unexpected input(s)` in the first log) before trusting a parameter, and treat
+any step whose output decides an irreversible action as something to unit-test with fixed
+inputs, not something to confirm by reading its YAML. And watch the first real run's
+*effect* (tags, npm), which is how both incidents were actually noticed.
diff --git a/tests/test_contract.py b/tests/test_contract.py
index 583aead..c25974a 100644
--- a/tests/test_contract.py
+++ b/tests/test_contract.py
@@ -645,6 +645,46 @@ class ContractTests(unittest.TestCase):
self.assertEqual(json.dumps(doc, sort_keys=True), json.dumps(doc, sort_keys=True))
self.assertEqual(list(json.loads(a).keys()), sorted(json.loads(a).keys()), "top-level keys sorted")
+ # ------------------------------------------------------------------ release version resolution
+ def test_release_version_resolver_rules(self):
+ """.github/scripts/resolve_version.py decides whether a push to main releases and what
+ version. Pinned with fake label data because the two incidents of 2026-09-11 (1.0.0-1.0.2,
+ then 1.0.4) were both a resolver doing something other than what its config was assumed
+ to mean, and nothing exercised the rules with fixed inputs."""
+ import importlib.util
+ spec = importlib.util.spec_from_file_location(
+ "resolve_version", ROOT / ".github" / "scripts" / "resolve_version.py")
+ rv = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(rv)
+
+ def labels(table):
+ return lambda n: table.get(n, [])
+
+ # chore-only / dependencies-only PRs release nothing (the 1.0.4 case)
+ v, _ = rv.resolve("1.0.3", ["chore(release): x (#145)"], labels({145: ["chore"]}))
+ self.assertIsNone(v)
+ v, _ = rv.resolve("1.0.3", ["build(deps): bump x (#132)"], labels({132: ["dependencies", "github_actions", "chore"]}))
+ self.assertIsNone(v)
+ # fix wins over chore on the same PR (#136 -> 1.0.3)
+ v, _ = rv.resolve("1.0.2", ["Fix the Codex install path (#136)"], labels({136: ["chore", "fix"]}))
+ self.assertEqual(v, "1.0.3")
+ # unlabeled PR still ships as a patch
+ v, _ = rv.resolve("1.0.3", ["Something (#150)"], labels({}))
+ self.assertEqual(v, "1.0.4")
+ # any minor among several -> minor, and patch digit resets
+ v, d = rv.resolve("1.0.3", ["Add x (#151)", "Fix y (#152)", "chore: z (#153)"],
+ labels({151: ["feature"], 152: ["fix"], 153: ["chore"]}))
+ self.assertEqual(v, "1.1.0")
+ self.assertEqual([x["bump"] for x in d], ["minor", "patch", None])
+ # a commit that came from no PR: patch unless its subject is chore/ci/docs/build
+ v, _ = rv.resolve("1.0.3", ["Fix by direct push"], labels({}))
+ self.assertEqual(v, "1.0.4")
+ v, _ = rv.resolve("1.0.3", ["docs: typo", "ci: retry", "chore(release): bump version to 1.0.3"], labels({}))
+ self.assertIsNone(v)
+ # major is never resolved automatically (the 1.0.0 case), whatever else is there
+ with self.assertRaises(SystemExit):
+ rv.resolve("1.0.3", ["Fix y (#152)", "Big (#154)"], labels({152: ["fix"], 154: ["major"]}))
+
# ------------------------------------------------------------------ consistency: MCP and installer
def test_mcp_tools_match_contract(self):
mcp_names = [t["name"] for t in mcp_server.tool_list()]