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
chore(release): never auto-bump the major, and stop releasing chore-only merges (#145)
Shogo Kajiyama1dc20bf13641
diff --git a/.github/release-drafter.yml b/.github/release-drafter.ymlindex 0f01fa9..4c7ed87 100644--- a/.github/release-drafter.yml+++ b/.github/release-drafter.yml@@ -2,16 +2,31 @@# - 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/major/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.+# 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.+#+# Two rules learned the hard way (2026-09-11, versions 1.0.0-1.0.2 published by accident):+# - `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.name-template: "v$RESOLVED_VERSION"tag-template: "v$RESOLVED_VERSION"+exclude-labels:+ - chore+ - ci+ - docs+ - dependenciescategories:- title: "Fixes"labels:@@ -21,11 +36,6 @@ categories:labels:- feature- enhancement- - title: "Other changes"- labels:- - chore- - docs- - cichange-template: "- $TITLE (#$NUMBER)"change-title-escapes: '\<*_&'autolabeler:@@ -37,16 +47,12 @@ autolabeler:title:- "/^add/i"- "/^feat/i"- - label: "major"- title:- - "/breaking/i"- body:- - "/BREAKING CHANGE/"- label: "chore"title:- "/^chore/i"- "/^ci:/i"- "/^docs/i"+ - "/^build\\(deps\\)/"files:- "*.md"- "docs/**"@@ -65,9 +71,6 @@ version-resolver:- patch- fix- bug- - chore- - docs- - cidefault: patchtemplate: |## What's Changeddiff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 6d7b51f..44cadb3 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -39,6 +39,13 @@ on:push:branches: [main]+# Two merges in quick succession must release one after the other, never side by side: each+# run resolves "the next version" from the same last tag, so two concurrent runs would both+# pick the same number and the second one's bump push / tag creation would collide.+concurrency:+ group: release+ cancel-in-progress: false+permissions:contents: writepull-requests: read # release-drafter reads merged PRs' labels to resolve the next version@@ -98,12 +105,21 @@ jobs:NEW_VERSION: ${{ steps.drafter.outputs.resolved_version }}run: |python3 - <<'PY'- import os, re, subprocess, pathlib+ import os, re, subprocess, pathlib, sysold = os.environ["OLD_VERSION"]new = os.environ["NEW_VERSION"]root = pathlib.Path(".")+ # An automatic bump never crosses a major boundary. 1.0.0-1.0.2 were published by+ # accident (2026-09-11) when a `major` label reached three dependency bumps through an+ # autolabeler rule; that rule is gone, but a hand-applied `major` label on the wrong PR+ # would do the same. A real major is a deliberate, manual package.json bump in a PR+ # (the existing manual path), never something this job infers from labels.+ if old.split(".")[0] != new.split(".")[0]:+ sys.exit(f"refusing to auto-bump across a major boundary ({old} -> {new}); "+ f"bump package.json by hand in a PR if a major release is intended")+pkg_path = root / "package.json"pkg = pkg_path.read_text(encoding="utf-8")pkg_new = re.sub(r'("version":\s*")[^"]+(")', rf'\g<1>{new}\g<2>', pkg, count=1)diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 9df3ab4..e9dc109 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -26,6 +26,8 @@ _Automated release: version and notes generated from pull requests merged since## 1.0.0+**Accidental major.** 1.0.0, 1.0.1 and 1.0.2 contain no user-facing or compatibility change over 0.16.15 -- they are three routine CI dependency bumps that a release-automation bug labelled `major` (see `references/process-pitfalls.md`, fixed in #145). They are left published because npm never lets a version number be reused; treat 1.0.x as 0.16.x under a different name.+_Automated release: version and notes generated from pull requests merged since 0.16.15._- build(deps): bump actions/upload-artifact from 4 to 7 (#133)diff --git a/README.md b/README.mdindex 09fb321..07bbaba 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 (`major`/`minor`/`feature`/`enhancement`/`fix`/`bug`/... — an unlabeled PR defaults to `patch`). 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/` changes → `chore`) as soon as it's opened — add a label yourself only to override that, or for `major`. 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 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.Contributing a change: see [CONTRIBUTING.md](CONTRIBUTING.md).diff --git a/references/process-pitfalls.md b/references/process-pitfalls.mdindex 158a08b..3fa7d1b 100644--- a/references/process-pitfalls.md+++ b/references/process-pitfalls.md@@ -103,3 +103,31 @@ shallow clone leaves no tag reachable to diff against, which would make the testskip itself in CI, not fail). If this test ever needs to skip a genuinely changelog-lessclosed issue (a pure process note, a duplicate, a revert of an unreleased change), name theexemption in the test itself with a reason — don't just widen the regex or drop the check.++## Automation that can publish must not take its "major" cue from text it did not write++On 2026-09-11, three routine Dependabot merges (`actions/upload-artifact` 4→7,+`actions/setup-node` 4→7, `dependabot/fetch-metadata` 2→3) were published to npm as+**1.0.0, 1.0.1 and 1.0.2**. The release pipeline (`release.yml`, since #129) resolves the next+version from PR labels; an autolabeler rule added the same day applied `major` to any PR whose+*body* contained the literal breaking-change marker. Dependabot PR bodies quote the upstream+project's release notes verbatim, and upload-artifact's v5.0.0 notes contain exactly that+phrase — about *their* Node runtime, nothing to do with this package. One label, three+accidental majors, in nine minutes, with every job green.++Two things made it worse than one bad rule: every chore merge released at all (so the first+accident was followed by two more before anyone looked), and nothing in the pipeline treated+"the major number changed" as different from any other bump.++Fixes (this commit): no autolabeler rule produces `major` any more; `chore`/`ci`/`docs`/+`dependencies` PRs are excluded from version resolution so they release nothing; `release.yml`+refuses to auto-bump across a major boundary regardless of labels; and the release job is+serialised (`concurrency`) so back-to-back merges cannot race on the bump push.++The general rule: a pipeline that publishes must never derive an irreversible decision (a+major bump, a publish, a tag) from text it did not author — PR bodies, commit messages and+release notes are quotations as often as they are statements. Match on labels a person+applied, or on files changed, and make the irreversible step refuse anything surprising rather+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.