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.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
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.ymlindex 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.pynew file mode 100644index 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.ymlindex 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 fromdiff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 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 apiid-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 labelsid: drafterif: steps.setup.outputs.needs_auto_bump == 'true'- uses: release-drafter/release-drafter@v6- with:- dry-run: trueenv:- 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 PRdiff --git a/README.md b/README.mdindex 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.mdindex 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 surthan assume the surprise was intended. And after wiring any such automation, watch the firstfew 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.pyindex 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 installerdef test_mcp_tools_match_contract(self):mcp_names = [t["name"] for t in mcp_server.tool_list()]