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.

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.yml
index 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
+ - dependencies
categories:
- title: "Fixes"
labels:
@@ -21,11 +36,6 @@ categories:
labels:
- feature
- enhancement
- - title: "Other changes"
- labels:
- - chore
- - docs
- - ci
change-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
- - ci
default: patch
template: |
## What's Changed
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 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: write
pull-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, sys
old = 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.md
index 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.md
index 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.md
index 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 test
skip itself in CI, not fail). If this test ever needs to skip a genuinely changelog-less
closed issue (a pure process note, a duplicate, a revert of an unreleased change), name the
exemption 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.