Skip to content

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

feat(docs): breaking changes appear on the public page only once a release ships them (#15601)

Bartosz Majewski518ae7091c35
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index fa327e3f635..1a852d0c6fe 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -15,7 +15,7 @@ Fixes # (issue)
### Breaking change? (required — CI fails if this is left unedited)
-<!-- Tick exactly one box. If either "yes", apply the "⛓️‍💥 breaking-change" label AND add an entry to docs/install/reference/breaking-changes.mdx (what changed + the action self-hosters must take). -->
+<!-- Tick exactly one box. If either "yes", apply the "⛓️‍💥 breaking-change" label AND add an entry at the top of docs/install/reference/breaking-changes-unreleased.mdx (what changed + the action self-hosters must take). The release moves it onto the public Breaking Changes page; never write a version heading by hand. -->
- [ ] no — reviewed, not breaking
- [ ] yes — technical (removed/renamed API field or endpoint, dropped column, new required field, removed/required env var)
diff --git a/.github/workflows/breaking-change-check.yml b/.github/workflows/breaking-change-check.yml
index 0aaeab0fc0e..bbc9d2d241c 100644
--- a/.github/workflows/breaking-change-check.yml
+++ b/.github/workflows/breaking-change-check.yml
@@ -21,6 +21,11 @@ jobs:
with:
bun-version: latest
+ - name: Test the breaking-changes scripts
+ run: |
+ bun test tools/scripts/breaking-changes-rollover.test.ts
+ bun tools/scripts/breaking-change-check.ts --self-check
+
- name: Check breaking-change declaration
env:
GITHUB_BASE_REF: ${{ github.event.pull_request.base.ref }}
diff --git a/.github/workflows/continuous-delivery-release.yml b/.github/workflows/continuous-delivery-release.yml
index ed797bedaa0..8d27904698f 100644
--- a/.github/workflows/continuous-delivery-release.yml
+++ b/.github/workflows/continuous-delivery-release.yml
@@ -10,6 +10,8 @@ jobs:
runs-on: ubuntu-24.04
environment:
name: release
+ outputs:
+ release: ${{ steps.version.outputs.release }}
steps:
- uses: actions/checkout@v5
with:
@@ -123,3 +125,77 @@ jobs:
gh release edit "$VERSION" --notes "${BODY}${NOTE}"
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+ sync-main:
+ needs: weekly-release
+ if: ${{ !cancelled() && needs.weekly-release.result == 'success' }}
+ runs-on: ubuntu-24.04
+ permissions:
+ contents: read
+ steps:
+ - uses: actions/checkout@v5
+ with:
+ ref: main
+ token: ${{ secrets.CROWDIN_PRS }}
+
+ - uses: oven-sh/setup-bun@v2
+ with:
+ bun-version: latest
+
+ - name: Roll unreleased breaking changes under the released version
+ env:
+ TAG: ${{ needs.weekly-release.outputs.release }}
+ run: |
+ git fetch --no-tags --depth=1 origin "refs/tags/$TAG:refs/tags/$TAG"
+ bun tools/scripts/breaking-changes-rollover.ts "$TAG"
+
+ - name: Push sync branch
+ id: push
+ env:
+ TAG: ${{ needs.weekly-release.outputs.release }}
+ run: |
+ git config --local user.email "[email protected]"
+ git config --local user.name "automated-commits-ap"
+ if git diff --quiet; then
+ echo "No breaking-change entry to roll over for $TAG."
+ exit 0
+ fi
+ BRANCH="automated/sync-main-$TAG"
+ git checkout -b "$BRANCH"
+ git add docs/install/reference/breaking-changes.mdx docs/install/reference/breaking-changes-unreleased.mdx
+ git commit -m "chore(release): sync main after $TAG"
+ git push -f origin "$BRANCH"
+ echo "branch=$BRANCH" >> $GITHUB_OUTPUT
+
+ - name: Open sync PR
+ if: steps.push.outputs.branch != ''
+ env:
+ GH_TOKEN: ${{ secrets.CROWDIN_PRS }}
+ TAG: ${{ needs.weekly-release.outputs.release }}
+ BRANCH: ${{ steps.push.outputs.branch }}
+ run: |
+ BODY="$(printf '%s\n' \
+ "The self-hosted release \`$TAG\` was published. This PR moves the breaking-change entries that \`$TAG\` contains from the hidden unreleased page under \`## $TAG\` on the Breaking Changes page. See SRE-232." \
+ "" \
+ "### Breaking change?" \
+ "" \
+ "- [x] no, reviewed, not breaking (entries are moved, none added)" \
+ "- [ ] yes, technical" \
+ "- [ ] yes, functional" \
+ "" \
+ "### Security impact?" \
+ "" \
+ "- [x] no, reviewed, no security impact" \
+ "- [ ] yes, security-sensitive")"
+ PR_NUMBER="$(gh pr list --head "$BRANCH" --state open --json number --jq '.[0].number // empty')"
+ if [ -n "$PR_NUMBER" ]; then
+ gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER" -X PATCH -f body="$BODY"
+ else
+ gh pr create \
+ --base main \
+ --head "$BRANCH" \
+ --title "chore(release): sync main after $TAG" \
+ --body "$BODY" \
+ --label skip-changelog \
+ --label automated
+ fi
diff --git a/.github/workflows/release-self-hosted.yml b/.github/workflows/release-self-hosted.yml
index 4277b30f0af..a42f44a2071 100644
--- a/.github/workflows/release-self-hosted.yml
+++ b/.github/workflows/release-self-hosted.yml
@@ -145,6 +145,17 @@ jobs:
ref: main
token: ${{ secrets.CROWDIN_PRS }}
+ - uses: oven-sh/setup-bun@v2
+ with:
+ bun-version: latest
+
+ - name: Roll unreleased breaking changes under the released version
+ env:
+ TAG: ${{ inputs.tag }}
+ run: |
+ git fetch --no-tags --depth=1 origin "refs/tags/$TAG:refs/tags/$TAG"
+ bun tools/scripts/breaking-changes-rollover.ts "$TAG"
+
- name: Check if main version is behind release
id: compare
env:
@@ -160,32 +171,51 @@ jobs:
echo "tag_base=$TAG_BASE" >> $GITHUB_OUTPUT
fi
- - name: Push version sync branch
- if: steps.compare.outputs.tag_base != ''
+ - name: Push sync branch
+ id: push
env:
TAG: ${{ inputs.tag }}
TAG_BASE: ${{ steps.compare.outputs.tag_base }}
run: |
git config --local user.email "[email protected]"
git config --local user.name "automated-commits-ap"
- npm pkg set version="$TAG_BASE"
- sed -i -E "s|(image: ghcr.io/activepieces/activepieces:)[0-9][0-9a-zA-Z.-]*|\1$TAG|" docker-compose.yml
- grep -q "image: ghcr.io/activepieces/activepieces:$TAG" docker-compose.yml
- sed -i -E "s|^appVersion: .*|appVersion: \"$TAG_BASE\"|" deploy/activepieces-helm/Chart.yaml
- git checkout -b "automated/sync-version-$TAG_BASE"
- git add package.json docker-compose.yml deploy/activepieces-helm/Chart.yaml
- git commit -m "chore(release): sync version to $TAG_BASE after off-cycle release"
- git push -f origin "automated/sync-version-$TAG_BASE"
+ if [ -n "$TAG_BASE" ]; then
+ npm pkg set version="$TAG_BASE"
+ sed -i -E "s|(image: ghcr.io/activepieces/activepieces:)[0-9][0-9a-zA-Z.-]*|\1$TAG|" docker-compose.yml
+ grep -q "image: ghcr.io/activepieces/activepieces:$TAG" docker-compose.yml
+ sed -i -E "s|^appVersion: .*|appVersion: \"$TAG_BASE\"|" deploy/activepieces-helm/Chart.yaml
+ fi
+ if git diff --quiet; then
+ echo "main already matches $TAG, nothing to sync."
+ exit 0
+ fi
+ BRANCH="automated/sync-main-$TAG"
+ git checkout -b "$BRANCH"
+ git add package.json docker-compose.yml deploy/activepieces-helm/Chart.yaml docs/install/reference/breaking-changes.mdx docs/install/reference/breaking-changes-unreleased.mdx
+ git commit -m "chore(release): sync main after $TAG"
+ git push -f origin "$BRANCH"
+ echo "branch=$BRANCH" >> $GITHUB_OUTPUT
- name: Open sync PR
- if: steps.compare.outputs.tag_base != ''
+ if: steps.push.outputs.branch != ''
env:
GH_TOKEN: ${{ secrets.CROWDIN_PRS }}
TAG: ${{ inputs.tag }}
- TAG_BASE: ${{ steps.compare.outputs.tag_base }}
+ BRANCH: ${{ steps.push.outputs.branch }}
run: |
- BRANCH="automated/sync-version-$TAG_BASE"
- BODY="The self-hosted release \`$TAG\` was published from a branch whose version bump is not on \`main\`. This PR syncs \`package.json\` and the \`docker-compose.yml\` image pin so the next weekly release does not read a stale version. Merge before the next release-candidate cut (Thursday 5 PM UTC). See GIT-1595."
+ BODY="$(printf '%s\n' \
+ "The self-hosted release \`$TAG\` was published. This PR syncs \`package.json\` and the \`docker-compose.yml\` image pin when \`main\` is behind, and moves the breaking-change entries that \`$TAG\` contains from the hidden unreleased page under \`## $TAG\` on the Breaking Changes page. Merge before the next release-candidate cut (Thursday 5 PM UTC). See GIT-1595 and SRE-232." \
+ "" \
+ "### Breaking change?" \
+ "" \
+ "- [x] no, reviewed, not breaking (entries are moved, none added)" \
+ "- [ ] yes, technical" \
+ "- [ ] yes, functional" \
+ "" \
+ "### Security impact?" \
+ "" \
+ "- [x] no, reviewed, no security impact" \
+ "- [ ] yes, security-sensitive")"
PR_NUMBER="$(gh pr list --head "$BRANCH" --state open --json number --jq '.[0].number // empty')"
if [ -n "$PR_NUMBER" ]; then
echo "An open sync PR from $BRANCH already exists, refreshing its body for $TAG."
@@ -194,7 +224,7 @@ jobs:
gh pr create \
--base main \
--head "$BRANCH" \
- --title "chore(release): sync version to $TAG_BASE after off-cycle release" \
+ --title "chore(release): sync main after $TAG" \
--body "$BODY" \
--label skip-changelog \
--label automated
diff --git a/AGENTS.md b/AGENTS.md
index 4ef35617243..e7f8168ecc8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -101,7 +101,7 @@ When running in `--mode=cloud`, do not use OAuth2 connections — the OAuth prov
- **`🧩 area/core-pieces`** — for core pieces (under `packages/pieces/core/`)
- **Always fill the "Breaking change?" section of the PR template** — tick exactly one box (the `breaking-change-check` CI job fails if it is left unedited). A change is breaking if a self-hoster or API consumer must take action: removed/renamed API fields or endpoints, dropped columns, new required fields, removed/required env vars, or default/limit/behaviour changes. If it is breaking:
- also apply the **`⛓️‍💥 breaking-change`** label (in addition to the primary label above), and
- - add an entry to `docs/install/reference/breaking-changes.mdx` describing what changed and the action required. CI enforces that the label and the docs entry travel together.
+ - add the entry at the top of `docs/install/reference/breaking-changes-unreleased.mdx` (a hidden page) describing what changed and the action required; the release moves it onto the Breaking Changes page under the release that ships it. Never write a version heading by hand. CI enforces that the label and the entry travel together.
- **Non-rollbackable migrations are a separate axis** from customer-facing breaking changes: a migration that runs destructive DDL (`DROP TABLE`/`DROP COLUMN`, `ADD ... NOT NULL` without `DEFAULT`, etc.) must set `breaking = true` on the migration class — this is the rollback-safety flag (used by `rollback-migrations.ts` and the release rollback note), enforced by `check-migration-rollback.ts`. It does **not** by itself require the `⛓️‍💥 breaking-change` label; decide that from the upgrade-impact question above.
## Database Migrations
diff --git a/CLAUDE.md b/CLAUDE.md
index 3d02a89cf98..f09401766b3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -105,7 +105,7 @@ When running in `--mode=cloud`, do not use OAuth2 connections — the OAuth prov
- `Security impact?` has **two**: `no`, `yes — security-sensitive` (touches authentication, secrets, permissions/roles, cryptography, SSRF / outbound HTTP, or file handling). This one is a **declaration only** — no label, no docs entry, nothing else is coupled to it.
- **If the change is breaking, the label and the docs entry must travel together** — the check's coupling is bidirectional and it also cross-checks the template answer, so label, docs entry and ticked box must all agree:
- apply the **`⛓️‍💥 breaking-change`** label (in addition to the primary label above), **and**
- - add an entry to `docs/install/reference/breaking-changes.mdx`. It must have a `####` title **and** at least one body line — a bare heading, a `---`, or loose prose does not count as an entry.
+ - add an entry at the top of `docs/install/reference/breaking-changes-unreleased.mdx` (a hidden page). It must have a `####` title **and** at least one body line — a bare heading, a `---`, or loose prose does not count as an entry. The release moves it onto the public Breaking Changes page under the version that ships it; never write a version heading by hand.
- Ticking `no` while carrying the label fails, and so does adding a docs entry without the label.
- **Never `gh run rerun` a `pull_request`-triggered check to pick up a PR description edit.** A rerun replays the *original* event payload, so it re-reads the stale body and fails again — and because it is a later attempt on an older run, its failure shadows a newer run that already passed. Edit the body (which fires `edited`, a trigger these workflows listen for) and let the fresh run supersede. To check the answer locally without any run at all: `PR_BODY="$(gh pr view <n> --json body --jq .body)" PR_LABELS="$(gh pr view <n> --json labels --jq '[.labels[].name]')" BASE_REF=main npx tsx tools/scripts/breaking-change-check.ts`
- **Non-rollbackable migrations are a separate axis** from customer-facing breaking changes: a migration that runs destructive DDL (`DROP TABLE`/`DROP COLUMN`, `ADD ... NOT NULL` without `DEFAULT`, etc.) must set `breaking = true` on the migration class — this is the rollback-safety flag (used by `rollback-migrations.ts` and the release rollback note), enforced by `check-migration-rollback.ts`. It does **not** by itself require the `⛓️‍💥 breaking-change` label; decide that from the upgrade-impact question above.
diff --git a/brain/knowledge/engineering/ci-pr-review-hygiene.md b/brain/knowledge/engineering/ci-pr-review-hygiene.md
index 6a8d0f2a4e6..31ccae1e390 100644
--- a/brain/knowledge/engineering/ci-pr-review-hygiene.md
+++ b/brain/knowledge/engineering/ci-pr-review-hygiene.md
@@ -78,9 +78,8 @@ Enforcement is the **`Codeowners review` repository ruleset** (active on the def
- **`license/cla` keys off the commit author email, so re-opening someone else's branch under your own name does not clear it.** CLA-assistant walks every commit in the PR rather than the PR author, and an author email that matches no GitHub account can never be matched to a signature — the 47 commits carried over onto [#15092](https://github.com/activepieces/activepieces/pull/15092) were authored as `[email protected]`, a local hostname, so the check sat at `not_signed` on a PR opened by a member. It is not in the `main` ruleset's required-checks list, but it is red on the page and a reviewer reads that as unmergeable. Either the original author signs through the PR link, or the commits get re-authored to an email tied to their GitHub account before you open it.
- **A branch that predates the `brain/` → `brain/knowledge/` move cannot edit a brain page in place — GitHub will call the PR conflicting even when `git merge` is clean locally.** Git follows the rename and merges the modification into the new path; GitHub's mergeability check does not, so it reports `modify/delete` on the old path and the PR goes `dirty`. Local `git merge-tree --write-tree` exits 0 and hides the problem; reproduce what GitHub sees with `git merge -X no-renames origin/main`. Fix: merge `origin/main` into the branch first, which lands the edit at the new path, then push.
- **Merging `main` into your branch makes Greptile review `main`'s shipped code as yours, and the score drops for files you never touched.** It appears to review the commits in the PR's range rather than the diff against the base, so a merge commit drags the commits it brought in along with it — [#15550](https://github.com/activepieces/activepieces/pull/15550) went 4/5 → 3/5 on a finding in `agent-conversation-service.ts` and `agent-run-controller.ts`, both arriving from #15548 in a merge done minutes earlier, neither in the PR's own diff. The check is one command: `git diff --name-only origin/main HEAD` — if a "Files Needing Attention" entry is not in that list, it is not this PR's. (Three-dot `origin/main...HEAD` works too; after merging `main` the merge base *is* `main`, so the two agree.) Do not stop at "not mine", though: that finding was real, a lookup by id with no `projectId` filter, and it is live on `main` where nobody is reviewing it any more — report it against the owning PR rather than letting the misattribution bury it. Rebasing instead of merging avoids the whole effect, but this repo merges, so expect it after every catch-up.
-- **`breaking-change-check` couples the docs entry to the label in BOTH directions, so back-documenting an already-shipped change drags the label onto a docs-only PR.** R3 in `tools/scripts/breaking-change-check.ts` fails a PR that adds a `####` entry to `docs/install/reference/breaking-changes.mdx` without `⛓️‍💥 breaking-change`, exactly as it fails the label without an entry — and the template answer has to agree too, so "yes" must be ticked on a PR that changes no code. It reads the *added lines of that one file* from `git diff origin/<base>...HEAD`, and `hasBreakingEntry` wants a `####` heading **plus** a non-heading body line, so a heading alone, a `---`, or a version bump does not count. Two consequences: the label then collides with `skip-changelog` in release-drafter (pick one deliberately — the feature's own PR usually already carried the changelog entry), and an entry appended to a *released* section still trips it, since the check never looks at which heading the lines landed under. **When the check fails, removing the label is sometimes the right fix, not writing an entry.** A long-lived branch can stop being breaking underneath you — merging `main` can delete the very thing that was breaking, and then the label and the template answer are both stale while the code is fine. Re-read what the branch still does against the template's own list before reaching for `breaking-changes.mdx`. Handy either way: the job re-runs on a **label change**, so flipping the label clears it with no empty commit and no push.
-- **A release cut empties `## Unreleased` into a version section, so a long-lived branch's entry conflicts in a way that is wrong to resolve by hand.** The entries do not move to the bottom of the file — the whole Unreleased block is relabelled as the new version and a fresh Unreleased is opened above it. A branch that added its entry weeks ago then conflicts against a section that has been relocated wholesale, and git presents it as "your entire block versus one stray line", which invites resolving the hunk in place. Doing that leaves the entry sitting inside an already-released section, where it is both wrong for readers and invisible to `breaking-change-check` (see the bullet above: the check never looks at which heading the added lines landed under, so CI stays green). Take main's copy of the file whole and re-insert the entry at the end of the *current* Unreleased section instead, then check that the entries you unioned on an earlier merge each appear exactly once — the previous resolution's placement is usually now a duplicate. Seen on GIT-1764 / #14899, which conflicted twice in one day for this reason.
-- **Nothing rolls `## Unreleased` over at release time, and the docs site is unversioned — so a breaking-changes entry has to name its own version.** No workflow or script writes to `docs/install/reference/breaking-changes.mdx` (`breaking-change-check.ts` only reads it), and `git log -S"## 0.88"` on the file comes back empty: the heading has not moved since 0.87.0, so entries for work that shipped months ago still sit under "Unreleased" (PM2 removal in 0.88.2, cache pre-warm gate and workspace naming in 0.89.0, …). `docs/docs.json` has no versioning either, so there is one live page for every self-hoster whatever version they run, published on merge rather than on release — the version heading is the *only* thing telling a reader whether a change is already in their build. So before adding an entry, run `git tag --contains <commit>` on the change it describes and file it under the release that actually shipped it; only genuinely unshipped work belongs under "Unreleased". What points self-hosters at the page in the first place is `release-drafter.yml`, which appends a "review the Breaking Changes page" line to every release body and groups `⛓️‍💥 breaking-change` PRs under their own heading — which also means a docs-only PR back-documenting an old change shows up in the *next* release's breaking-change list.
+- **`breaking-change-check` couples the docs entry to the label in BOTH directions, so back-documenting an already-shipped change drags the label onto a docs-only PR.** R3 in `tools/scripts/breaking-change-check.ts` fails a PR that adds a `####` entry to the hidden page `docs/install/reference/breaking-changes-unreleased.mdx` without `⛓️‍💥 breaking-change`, exactly as it fails the label without an entry — and the template answer has to agree too, so "yes" must be ticked on a PR that changes no code. It reads the *added lines of that one file* from `git diff origin/<base>...HEAD`, and `hasBreakingEntry` wants a `####` heading **plus** a non-heading body line, so a heading alone, a `---`, or a version bump does not count. Two consequences: the label then collides with `skip-changelog` in release-drafter (pick one deliberately — the feature's own PR usually already carried the changelog entry) — though back-documenting on the public page itself no longer trips it, since R3 only reads the hidden page. **When the check fails, removing the label is sometimes the right fix, not writing an entry.** A long-lived branch can stop being breaking underneath you — merging `main` can delete the very thing that was breaking, and then the label and the template answer are both stale while the code is fine. Re-read what the branch still does against the template's own list before reaching for the hidden page. Handy either way: the job re-runs on a **label change**, so flipping the label clears it with no empty commit and no push.
+- **Breaking-change entries are written on the hidden page `docs/install/reference/breaking-changes-unreleased.mdx`, never under a version heading.** `release-self-hosted.yml`'s `sync-version-to-main` job runs `tools/scripts/breaking-changes-rollover.ts` after every release: it reads the hidden page as it was at the tag (`git show <tag>:<hidden page>`) and moves every entry that already existed then under `## <tag>` on the public page, in the same automated PR that syncs the version. The public page is unversioned and deployed on merge, so anything written there is public immediately; `breaking-change-check.ts` fails a PR that re-adds `## Unreleased` to it, and its label-to-entry coupling (R3) now reads the hidden page, so back-documenting an old change on the public page no longer drags the label along (SRE-232, #15592).
- **Greptile enforces the file-order rule on *private* constants too, which CLAUDE.md only states for exported ones.** CLAUDE.md says "Exported types and constants must be placed at the end of the file" and gives the order as imports → exports → helpers → types; Greptile reads that as covering module-private constants as well, and flags a `const` sitting above the file's exported symbol (P2 on [#15226](https://github.com/activepieces/activepieces/pull/15226), for two constants only read inside the service they sat above). It has that as a stored custom-context memory, so it will keep raising it. Put private constants in the helpers section below the export — hoisting is a non-issue when they are only read at call time.
- **`turbo run lint --filter=<pkg>` never typechecks that package, so "0 errors" is no proof it compiles — run `turbo run build --filter=<pkg>` as well.** A package's `lint` script is `eslint 'src/**/*.ts'` with no `tsc`, and the turbo `lint` task's `dependsOn: ["^build"]` builds the package's *upstream dependencies* only, never itself — the `^` is the whole story. So a type error in the package you are editing is invisible to a filtered lint run. CI still catches it, but confusingly under the **lint** job as well as **main**, because linting the whole repo makes your package an upstream of something else whose `^build` finally compiles it. A branch can therefore sit red on two jobs for one `tsc` error that a local filtered lint reported clean.
- **Never set `maxWorkers` in `packages/server/api/vitest.config.ts` — the api suites are not alone on the runner.** `ci.yml` runs `turbo run test-ce test-ee test-cloud check-migrations --filter=api` as concurrent turbo tasks, in parallel with a second `turbo run test` line and `web#build`'s vite run, all on one 4-vCPU / 16 GB `ubuntu-latest` box. Each vitest fork boots a Fastify server *and* a PGlite database, so the config's per-project worker count is really that number **times three editions**. A stray `maxWorkers: 4` on [#14777](https://github.com/activepieces/activepieces/pull/14777) raised the forks pool from its default `availableParallelism() - 1` (3) to 4 — 12 forks instead of 9 — and took the job down twice in a row with failures that never named the cause: first `execute-flow-e2e`'s `beforeAll` timing out while **1028 tests passed**, then the whole runner SIGKILLed mid-build (`web#build exited (137)`, `check-migrations` SIGTERM, api suites never finishing). Both read as "a test broke". Neither was. The tell is `The runner has received a shutdown signal` immediately above the 137, and the fix is to delete the line, not to raise a timeout. Same reason the config's `hookTimeout` is 120s: a loaded runner pushes a server boot past a minute, so a file that pins its own smaller `beforeAll` timeout (`}, 30_000)`) silently opts out of the protection and becomes the first thing to fail. Check the blast radius before calling it fixed: a config mistake made on a long-lived stack branch replicates by merge into every descendant, so deleting it from the PR in front of you leaves the rest of the stack to reintroduce it on the next rebase. This one originated once on `feat/subflow-fan-in-barrier` (2026-08-12) and reached **14 branches, 13 of them open PRs** across three unrelated stacks — `git log -S maxWorkers` over `origin/main` proved it never landed there, and a loop of `git show <branch>:<path> | grep` found every branch still carrying it.
diff --git a/docs/handbook/engineering/playbooks/releases.mdx b/docs/handbook/engineering/playbooks/releases.mdx
index f27b819fc95..ea6ba02d23d 100644
--- a/docs/handbook/engineering/playbooks/releases.mdx
+++ b/docs/handbook/engineering/playbooks/releases.mdx
@@ -94,7 +94,7 @@ Manual dispatch only. Prompts for a **release tag** (e.g., `0.79.2` or `0.79.2-h
This is the **only** release path that takes a free-text version — the scheduled `continuous-delivery-release.yml` and `continuous-delivery-canary.yml` both derive the version from `package.json` (`node --print "require('./package.json').version"`) and never ask a human. The free-text input exists precisely because off-cycle patches carry deploy-only suffixes (`-hotfix.N`, `-rc.N`) that don't live in `package.json`. Because `package.json` is the single runtime source of truth (`apVersionUtil.getCurrentRelease` reads it, and it's baked into the image from source), a mistyped tag would publish an image whose real version disagrees with its tag — invisible until it's mixed with a correctly-built peer and the worker↔app version gate silently withholds jobs. The **`Verify tag matches package.json`** step fails the release when the tag's base `X.Y.Z` (suffix stripped) doesn't equal `package.json`, so bump `package.json` (or fix the tag) before releasing.
-Because the bump commit for an off-cycle release lives on its release branch, `main`'s `package.json` would otherwise stay stale, and the next weekly release then reads the old version at the `release-candidate` ref and refuses to overwrite the already-existing tag (this is how 0.85.4/0.85.5 came to report 0.85.2). To close that loop, a **`sync-version-to-main`** job runs after every successful release: if `main`'s version is behind the released base version, it opens an automated PR (branch `automated/sync-version-X.Y.Z`, pushed and created with the automated-PR token so CI runs on it) setting `package.json` to the base version and the `docker-compose.yml` image pins to the full released tag. **Merge that PR before the next release-candidate cut (Thursday 5 PM UTC).** The weekly release reads the version at the `release-candidate` ref, so merging after the cut is too late. If `main` is already at or ahead of the released version, the job no-ops. The job lives in the workflow definition at the dispatched ref, so releases run from branches cut before it existed won't open a sync PR. Check `main`'s version manually in that case.
+Because the bump commit for an off-cycle release lives on its release branch, `main`'s `package.json` would otherwise stay stale, and the next weekly release then reads the old version at the `release-candidate` ref and refuses to overwrite the already-existing tag (this is how 0.85.4/0.85.5 came to report 0.85.2). To close that loop, a **`sync-version-to-main`** job runs after every successful release: if `main`'s version is behind the released base version, it opens an automated PR (branch `automated/sync-main-<tag>`, one per tag so a hotfix never overwrites a pending base-release PR, pushed and created with the automated-PR token so CI runs on it) setting `package.json` to the base version and the `docker-compose.yml` image pins to the full released tag. **Merge that PR before the next release-candidate cut (Thursday 5 PM UTC).** The weekly release reads the version at the `release-candidate` ref, so merging after the cut is too late. The same job runs `tools/scripts/breaking-changes-rollover.ts`: every entry on the hidden `docs/install/reference/breaking-changes-unreleased.mdx` page that already existed at the released tag is moved under `## <tag>` on the public Breaking Changes page, so the PR opens whenever the version or the breaking-changes pages need syncing, not only when the version is behind. If neither needs a change, the job no-ops. The weekly `continuous-delivery-release.yml` runs the same rollover in its `sync-main` job, so both release paths file entries under the tag that shipped them. The job lives in the workflow definition at the dispatched ref, so releases run from branches cut before it existed won't open a sync PR. Check `main`'s version manually in that case.
### `publish-embed-sdk.yml`
diff --git a/docs/install/reference/breaking-changes-unreleased.mdx b/docs/install/reference/breaking-changes-unreleased.mdx
new file mode 100644
index 00000000000..6fdd6672f5e
--- /dev/null
+++ b/docs/install/reference/breaking-changes-unreleased.mdx
@@ -0,0 +1,80 @@
+---
+title: "Unreleased breaking changes"
+description: "Changes merged to main that no self-hosted release contains yet."
+hidden: true
+---
+
+Entries here move to [Breaking Changes](/install/reference/breaking-changes) automatically when the release that contains them is tagged. Add new entries at the top, right under the heading below.
+
+## What has changed?
+
+#### Telegram Bot Get Chat and Get Chat Member fail on Telegram errors, and Get File no longer returns the bot token
+
+Get Chat and Get Chat Member used to return Telegram's error response, such as `{ "ok": false, "description": "Bad Request: chat not found" }`, as a **successful** step. From Telegram Bot 0.8.0 the step fails with that error instead, so a wrong chat or user ID stops the flow where it happened.
+
+Get File used to return a `file_url` that contained the bot token, which put the token in the run's step output. From 0.8.0 the output no longer has `file_url`. With **Download File** on, it still returns the content as `file_content_base64`.
+
+#### What you need to do
+
+If a flow branches on Get Chat or Get Chat Member returning `ok: false`, handle the failure with the step's error handling options instead. If a later step reads Get File's `file_url`, turn on **Download File** and use `file_content_base64`. Steps keep running on the version they were built with until you upgrade them.
+
+#### Helm chart 0.5.0 uses the cluster's default StorageClass again
+
+Chart 0.4.0 set the app's cache volume to the `local-path` StorageClass whenever `persistence.storageClassName` was unset, which only exists on k3s-style clusters, so new installs elsewhere stayed `Pending`. From 0.5.0 an unset value uses the cluster's default StorageClass again, as chart 0.3.x did. A StatefulSet's volume class cannot change after it is created, so `helm upgrade` keeps the class your release already uses.
+
+#### What you need to do
+
+If your release was created with chart 0.4.0, you never set `persistence.storageClassName`, and you deploy by rendering the chart without a cluster connection (Argo CD, `helm template | kubectl apply`), pin the class your StatefulSet was created with before upgrading, or every sync fails with `updates to statefulset spec ... are forbidden`:
+
+```yaml
+persistence:
+ storageClassName: "local-path"
+```
+
+Direct `helm upgrade` needs no change. A new install on a cluster with no default StorageClass (`kubectl get storageclass` shows none marked `(default)`) must set `persistence.storageClassName`, or the cache volume and the app pod stay `Pending`.
+
+#### Zoho CRM Read File and Custom API Call only send the token to the connection's Zoho CRM hosts
+
+Read File used to send the connection's Zoho access token to whatever URL it was given, including hosts outside Zoho. From Zoho CRM 0.4.0 it only fetches `https` URLs on the connection's own Zoho API host under `/crm/` (for example `https://www.zohoapis.com/crm/bulk/v8/read/<job>/result`), or on that data centre's download hosts (for example `https://download-accl.zoho.com/v2/crm/...` for a data backup). Custom Zoho function URLs (`/crm/.../functions/...`) and URLs in another data centre are refused. Any other URL fails before a request is made. Redirects are followed only to those same hosts; a redirect anywhere else stops the download before that host is requested. The file is streamed, so the deployment's file size limit (`AP_MAX_FILE_SIZE_MB`) applies.
+
+Custom API Call keeps working with paths such as `/Leads` and with full URLs on the connection's own API host (for example `https://www.zohoapis.com/crm/v8/...`). A full URL on any other host, including other Zoho hosts, now fails before a request is made instead of receiving the token.
+
+#### What you need to do
+
+Nothing if your Read File steps point at Zoho CRM backup, bulk-read or API file URLs of the connected account, and your Custom API Call steps use a path or a URL on the connection's API host. If a step calls any other URL, replace it with the HTTP piece's Send HTTP Request action. Steps keep running on the version they were built with until you upgrade them.
+
+#### Instagram for Business no longer reports success when a reel fails to publish
+
+Publishing a reel uploads the video to Instagram and then waits for Instagram to finish processing it before the post goes live. The piece used to give up after about a hundred seconds and return the boolean `false`, which the flow recorded as a **successful** step. Anything downstream carried on with `false` where a media id was expected, and nothing in the run said the post had not been published.
+
+Upload Reel now throws when Instagram reports an error, and waits up to five minutes, which is the window Instagram's own guidance describes. Upload Photo waits for the same signal instead of publishing blind, so a container Instagram rejects now surfaces as a failed step rather than a confusing error from the next call.
+
+The piece also moves from Graph API v17.0, which expired on 12 September 2025, to v23.0.
+
+#### What you need to do
+
+If a flow branches on the output of Upload Reel being `false`, that branch will no longer be taken — the step fails instead. Handle the failure with the step's error handling options, or with a branch on the run status.
+
+Reconnect your Instagram connections. The piece now requests the permissions needed for comments, insights, content management, direct messages and Page metadata, and a token issued before this release does not carry them. Steps that were saved earlier will also ask you to select the Page again, because messaging needs the Facebook Page id that the Page dropdown now stores.
+
+#### WhatsApp Business' Send Message and Send Media return the API response instead of the HTTP envelope
+
+The WhatsApp Business piece returned two different shapes depending on which action you used. `Send Template Message` returned the WhatsApp Cloud API payload directly, while `Send Message` and `Send Media` returned the whole HTTP response, so the same payload sat one level down under `body`, alongside `status` and `headers`.
+
+Both actions now return the API payload directly, matching `Send Template Message` and every other action in the piece. A step that produced
+
+```json
+{ "status": 200, "headers": { }, "body": { "messaging_product": "whatsapp", "messages": [{ "id": "wamid.…" }] } }
+```
+
+now produces
+
+```json
+{ "messaging_product": "whatsapp", "contacts": [{ "input": "…", "wa_id": "…" }], "messages": [{ "id": "wamid.…" }] }
+```
+
+The whole piece also moves to Graph API `v23.0`, via a single `WHATSAPP_API_BASE` constant. It previously split between `v17.0` (expired September 2025) and `v20.0` (expires 24 September 2026).
+
+#### What you need to do
+
+Update any step that reads the output of `Send Message` or `Send Media`. Drop the `body.` prefix: `{{step.body.messages[0].id}}` becomes `{{step.messages[0].id}}`. Steps that only send and ignore the output need no change, and no connection has to be re-authorised.
diff --git a/docs/install/reference/breaking-changes.mdx b/docs/install/reference/breaking-changes.mdx
index 0da704c22d2..d6bf19f7101 100644
--- a/docs/install/reference/breaking-changes.mdx
+++ b/docs/install/reference/breaking-changes.mdx
@@ -4,97 +4,10 @@ description: "This list shows all versions that include breaking changes and how
icon: "hammer"
---
-## Unreleased
+## 0.92.0
### What has changed?
-#### Square 1.0.0 removes the New Invoice and New Appointment triggers
-
-Square 1.0.0 removes the **New Invoice** and **New Appointment** triggers. It also stops requesting the `INVOICES_READ`, `APPOINTMENTS_READ` and `APPOINTMENTS_WRITE` permissions, which nothing in the piece uses any more, and requests `PAYMENTS_WRITE`, `INVENTORY_READ`, `INVENTORY_WRITE` and `EMPLOYEES_READ` for the new payment, inventory and team actions.
-
-#### What you need to do
-
-Flows keep running on the Square version they were built with. If a flow starts with New Invoice or New Appointment, keep its Square trigger on its current version. To move it to 1.0.0, replace the trigger with the **Webhook** piece, subscribed in the Square Developer Console to `invoice.created` or `booking.created`. The webhook already carries the invoice or booking. To read the full record with **Custom API Call** (`GET /v2/invoices/{id}` or `GET /v2/bookings/{id}`), use a Square connection created before 1.0.0, because connections created or reconnected on 1.0.0 no longer have the invoice and appointment read permissions. Existing Square connections keep working. Reconnect Square only for the new actions that need payment, inventory or team permissions, and keep a separate older connection for invoice or booking reads.
-
-#### Total CMS 1.0.0 supports Total CMS 3 only
-
-Total CMS 0.2.0 called the Total CMS 1 and 2 API (`rw_common/plugins/stacks/total-cms/totalapi.php` with a license key), which Total CMS 3 no longer has. From 1.0.0 the piece uses the Total CMS 3 REST API. The connection now takes a **Site URL** and an **API Key** (Utilities → API Keys in the Total CMS admin, Pro edition) instead of a domain and license key.
-
-Actions now take a Collection ID and an Object ID instead of a "CMS ID", and a blog post's permalink is now its Post ID. The thumbnail, scale, crop and extension options on image actions are removed, because Total CMS 3 resizes images on request through ImageWorks. The RSS title and description, genre, labels, extra2 and archived fields on blog posts are removed, because the Total CMS 3 blog schema does not have them. Get Content takes a collection instead of a data type, Save Date takes a date and time instead of a Unix timestamp, and New Blog Post takes a blog collection, fires on the post's created time and skips drafts by default.
-
-#### What you need to do
-
-Upgrade the site to Total CMS 3, create an API key and reconnect with the Site URL and API Key. Then upgrade each Total CMS step to 1.0.0 and map its inputs again. Steps keep running on the version they were built with until you upgrade them, and those steps stop working once the site runs Total CMS 3.
-
-#### AI steps and agents stop running a model their key no longer allows
-
-An AI provider key can limit which models it offers. Until now, a flow AI step or a flow-step agent that already named a model kept running it after an admin removed that model from the key's list. From this release the step fails with "The model … isn't allowed for this AI provider key anymore". This is checked when the step is queued and again when it runs.
-
-Two key edits are now refused instead of silently breaking things: limiting the projects of a key that web search, web scraping or image generation uses for every project, and removing a typed-in model (Vertex, OpenAI-compatible, Cloudflare) that a platform tier uses. Platform-wide AI work, such as tool-search embeddings, now prefers a key that serves every project over one limited to a few.
-
-#### What you need to do
-
-If a flow step or agent fails with that message, pick a model the key allows, or add the model back to the key's list in AI Center. To limit a capability key's projects, choose a different key for that capability first.
-
-#### Telegram Bot Get Chat and Get Chat Member fail on Telegram errors, and Get File no longer returns the bot token
-
-Get Chat and Get Chat Member used to return Telegram's error response, such as `{ "ok": false, "description": "Bad Request: chat not found" }`, as a **successful** step. From Telegram Bot 0.8.0 the step fails with that error instead, so a wrong chat or user ID stops the flow where it happened.
-
-Get File used to return a `file_url` that contained the bot token, which put the token in the run's step output. From 0.8.0 the output no longer has `file_url`. With **Download File** on, it still returns the content as `file_content_base64`.
-
-#### What you need to do
-
-If a flow branches on Get Chat or Get Chat Member returning `ok: false`, handle the failure with the step's error handling options instead. If a later step reads Get File's `file_url`, turn on **Download File** and use `file_content_base64`. Steps keep running on the version they were built with until you upgrade them.
-
-#### Xero connections request Xero's granular scopes
-
-Since 2 March 2026 Xero refuses the broad scopes `accounting.transactions`, `accounting.reports.read` and `accounting.journals.read` for newly created Xero apps, so connecting such an app failed with `invalid_scope`. From Xero 0.8.0, new connections request the granular scopes instead: `accounting.invoices`, `accounting.payments`, `accounting.banktransactions`, `accounting.manualjournals` and the per-report scopes (aged, balance sheet, bank summary, executive summary, profit and loss, tax and trial balance reports). Existing connections are unaffected: Xero keeps the permissions granted at sign-in, and token refresh sends no scope.
-
-New connections no longer have Xero's Receipts, Expense Claims or Journals permissions, because Xero does not grant `accounting.classicexpenses` or `accounting.journals.read` to new apps. On those connections, Upload Attachment with the Receipt resource type fails with a message saying so, and Custom API Call to `/Receipts`, `/ExpenseClaims` or `/Journals` returns 401 or 403.
-
-#### What you need to do
-
-Nothing for existing Xero connections. To connect a Xero app created on or after 2 March 2026, upgrade the Xero step to 0.8.0 or later before creating the connection; a connection created from a step still on an earlier version requests the old scopes. Keep a connection created before 0.8.0 if your flows attach files to Receipts or call the Receipts, Expense Claims or Journals endpoints.
-
-#### Helm chart 0.5.0 uses the cluster's default StorageClass again
-
-Chart 0.4.0 set the app's cache volume to the `local-path` StorageClass whenever `persistence.storageClassName` was unset, which only exists on k3s-style clusters, so new installs elsewhere stayed `Pending`. From 0.5.0 an unset value uses the cluster's default StorageClass again, as chart 0.3.x did. A StatefulSet's volume class cannot change after it is created, so `helm upgrade` keeps the class your release already uses.
-
-#### What you need to do
-
-If your release was created with chart 0.4.0, you never set `persistence.storageClassName`, and you deploy by rendering the chart without a cluster connection (Argo CD, `helm template | kubectl apply`), pin the class your StatefulSet was created with before upgrading, or every sync fails with `updates to statefulset spec ... are forbidden`:
-
-```yaml
-persistence:
- storageClassName: "local-path"
-```
-
-Direct `helm upgrade` needs no change. A new install on a cluster with no default StorageClass (`kubectl get storageclass` shows none marked `(default)`) must set `persistence.storageClassName`, or the cache volume and the app pod stay `Pending`.
-
-#### Zoho CRM Read File and Custom API Call only send the token to the connection's Zoho CRM hosts
-
-Read File used to send the connection's Zoho access token to whatever URL it was given, including hosts outside Zoho. From Zoho CRM 0.4.0 it only fetches `https` URLs on the connection's own Zoho API host under `/crm/` (for example `https://www.zohoapis.com/crm/bulk/v8/read/<job>/result`), or on that data centre's download hosts (for example `https://download-accl.zoho.com/v2/crm/...` for a data backup). Custom Zoho function URLs (`/crm/.../functions/...`) and URLs in another data centre are refused. Any other URL fails before a request is made. Redirects are followed only to those same hosts; a redirect anywhere else stops the download before that host is requested. The file is streamed, so the deployment's file size limit (`AP_MAX_FILE_SIZE_MB`) applies.
-
-Custom API Call keeps working with paths such as `/Leads` and with full URLs on the connection's own API host (for example `https://www.zohoapis.com/crm/v8/...`). A full URL on any other host, including other Zoho hosts, now fails before a request is made instead of receiving the token.
-
-#### What you need to do
-
-Nothing if your Read File steps point at Zoho CRM backup, bulk-read or API file URLs of the connected account, and your Custom API Call steps use a path or a URL on the connection's API host. If a step calls any other URL, replace it with the HTTP piece's Send HTTP Request action. Steps keep running on the version they were built with until you upgrade them.
-
-#### Instagram for Business no longer reports success when a reel fails to publish
-
-Publishing a reel uploads the video to Instagram and then waits for Instagram to finish processing it before the post goes live. The piece used to give up after about a hundred seconds and return the boolean `false`, which the flow recorded as a **successful** step. Anything downstream carried on with `false` where a media id was expected, and nothing in the run said the post had not been published.
-
-Upload Reel now throws when Instagram reports an error, and waits up to five minutes, which is the window Instagram's own guidance describes. Upload Photo waits for the same signal instead of publishing blind, so a container Instagram rejects now surfaces as a failed step rather than a confusing error from the next call.
-
-The piece also moves from Graph API v17.0, which expired on 12 September 2025, to v23.0.
-
-#### What you need to do
-
-If a flow branches on the output of Upload Reel being `false`, that branch will no longer be taken — the step fails instead. Handle the failure with the step's error handling options, or with a branch on the run status.
-
-Reconnect your Instagram connections. The piece now requests the permissions needed for comments, insights, content management, direct messages and Page metadata, and a token issued before this release does not carry them. Steps that were saved earlier will also ask you to select the Page again, because messaging needs the Facebook Page id that the Page dropdown now stores.
-
#### The AI provider config endpoint is removed
`GET /v1/ai-providers/:provider/config` returned a provider's decrypted credentials so that an AI step running inside the engine could build the model itself and call the provider directly. AI steps no longer work that way: the worker resolves the credentials and makes the call, which is what lets Activepieces charge managed AI on what the call actually cost. Nothing in the product calls the endpoint any more, and it now returns `404`.
@@ -176,28 +89,6 @@ Clearing a description from this action is therefore no longer possible; that is
Nothing unless a flow or an agent relied on a blank description to clear a board's description, which previously happened on every run whether or not it was intended. Clear it from Pinterest directly.
-#### WhatsApp Business' Send Message and Send Media return the API response instead of the HTTP envelope
-
-The WhatsApp Business piece returned two different shapes depending on which action you used. `Send Template Message` returned the WhatsApp Cloud API payload directly, while `Send Message` and `Send Media` returned the whole HTTP response, so the same payload sat one level down under `body`, alongside `status` and `headers`.
-
-Both actions now return the API payload directly, matching `Send Template Message` and every other action in the piece. A step that produced
-
-```json
-{ "status": 200, "headers": { }, "body": { "messaging_product": "whatsapp", "messages": [{ "id": "wamid.…" }] } }
-```
-
-now produces
-
-```json
-{ "messaging_product": "whatsapp", "contacts": [{ "input": "…", "wa_id": "…" }], "messages": [{ "id": "wamid.…" }] }
-```
-
-The whole piece also moves to Graph API `v23.0`, via a single `WHATSAPP_API_BASE` constant. It previously split between `v17.0` (expired September 2025) and `v20.0` (expires 24 September 2026).
-
-#### What you need to do
-
-Update any step that reads the output of `Send Message` or `Send Media`. Drop the `body.` prefix: `{{step.body.messages[0].id}}` becomes `{{step.messages[0].id}}`. Steps that only send and ignore the output need no change, and no connection has to be re-authorised.
-
## 0.91.0
### What has changed?
diff --git a/tools/scripts/breaking-change-check.ts b/tools/scripts/breaking-change-check.ts
index 2dd1bab3bbb..b0cba040c51 100644
--- a/tools/scripts/breaking-change-check.ts
+++ b/tools/scripts/breaking-change-check.ts
@@ -2,7 +2,9 @@ import assert from 'assert'
import { execSync } from 'child_process'
const BREAKING_LABEL = '⛓️‍💥 breaking-change'
-const BREAKING_CHANGES_DOC = 'docs/install/reference/breaking-changes.mdx'
+const UNRELEASED_DOC = 'docs/install/reference/breaking-changes-unreleased.mdx'
+const PUBLISHED_DOC = 'docs/install/reference/breaking-changes.mdx'
+const UNRELEASED_HEADING = /^##\s+Unreleased\b/i
type TemplateChoice = 'yes' | 'no' | 'unset' | 'multiple'
@@ -61,7 +63,8 @@ function main(): void {
const hasBreakingLabel = labels.includes(BREAKING_LABEL)
const templateChoice = sectionChoice({ body, heading: /^#{2,3}\s*Breaking change\?/im })
const securityChoice = sectionChoice({ body, heading: /^#{2,3}\s*Security impact\?/im })
- const docAdded = hasBreakingEntry(addedDocLines({ baseRef, file: BREAKING_CHANGES_DOC }))
+ const docAdded = hasBreakingEntry(addedDocLines({ baseRef, file: UNRELEASED_DOC }))
+ const publishedAdded = addedDocLines({ baseRef, file: PUBLISHED_DOC })
const errors: string[] = []
@@ -83,10 +86,13 @@ function main(): void {
// R3 — the breaking label, the template answer, and the docs entry must agree.
if (hasBreakingLabel && !docAdded) {
- errors.push(`PR carries the "${BREAKING_LABEL}" label but adds no entry to ${BREAKING_CHANGES_DOC}. Document the change (what changed + required action) so it reaches self-hosters.`)
+ errors.push(`PR carries the "${BREAKING_LABEL}" label but adds no entry to ${UNRELEASED_DOC}. Document the change (what changed + required action) at the top of that page; the release moves it onto ${PUBLISHED_DOC}.`)
}
if (docAdded && !hasBreakingLabel) {
- errors.push(`PR adds an entry to ${BREAKING_CHANGES_DOC} but is missing the "${BREAKING_LABEL}" label. Apply the label so it lands in the release notes.`)
+ errors.push(`PR adds an entry to ${UNRELEASED_DOC} but is missing the "${BREAKING_LABEL}" label. Apply the label so it lands in the release notes.`)
+ }
+ if (publishedAdded.some((line) => UNRELEASED_HEADING.test(line))) {
+ errors.push(`"## Unreleased" no longer exists on ${PUBLISHED_DOC}. Add the entry to ${UNRELEASED_DOC} instead; the release rolls it under the version that ships it.`)
}
if (templateChoice === 'yes' && !hasBreakingLabel) {
errors.push(`The PR template declares a breaking change but the "${BREAKING_LABEL}" label is missing. Apply it.`)
@@ -100,7 +106,7 @@ function main(): void {
for (const error of errors) {
console.error(` - ${error}`)
}
- console.error('\nSee docs/install/reference/breaking-changes.mdx and the PR template for guidance.')
+ console.error(`\nSee ${UNRELEASED_DOC} and the PR template for guidance.`)
process.exit(1)
}
@@ -113,6 +119,8 @@ function runSelfCheck(): void {
assert(hasBreakingEntry(['---']) === false, 'a separator is not an entry')
assert(hasBreakingEntry(['## 0.87.0', 'Set AP_FOO is gone.']) === false, 'a version bump without a #### title is not an entry')
assert(hasBreakingEntry(['Just a stray sentence.']) === false, 'placeholder prose without a title is not an entry')
+ assert(UNRELEASED_HEADING.test('## Unreleased') === true, 'a hand-written Unreleased heading is detected')
+ assert(UNRELEASED_HEADING.test('## 0.92.0') === false, 'a version heading is not an Unreleased heading')
console.log('breaking-change-check self-check passed')
}
diff --git a/tools/scripts/breaking-changes-rollover.test.ts b/tools/scripts/breaking-changes-rollover.test.ts
new file mode 100644
index 00000000000..482cdef0480
--- /dev/null
+++ b/tools/scripts/breaking-changes-rollover.test.ts
@@ -0,0 +1,92 @@
+import { describe, expect, it } from 'bun:test'
+import { breakingChangesRollover } from './breaking-changes-rollover'
+
+const entry = ({ title, body }: { title: string, body: string }): string =>
+ `#### ${title}\n\n${body}\n\n#### What you need to do\n\nNothing for ${title}.`
+
+const hiddenPage = ({ entries }: { entries: string[] }): string =>
+ `---\ntitle: "Unreleased breaking changes"\nhidden: true\n---\n\nIntro sentence.\n\n## What has changed?\n\n${entries.join('\n\n')}\n`
+
+const publishedPage = ({ sections }: { sections: string }): string =>
+ `---\ntitle: "Breaking Changes"\n---\n\n${sections}`
+
+const alpha = entry({ title: 'Alpha changes', body: 'Alpha body.' })
+const beta = entry({ title: '`AP_BETA` is removed', body: 'Beta body.' })
+const gamma = entry({ title: 'Gamma changes', body: 'Gamma body.' })
+
+describe('rollover', () => {
+ it('moves entries present at the tag into a new version section right after the frontmatter', () => {
+ const result = breakingChangesRollover.rollover({
+ hidden: hiddenPage({ entries: [gamma, alpha] }),
+ snapshot: hiddenPage({ entries: [alpha] }),
+ published: publishedPage({ sections: '## 0.91.0\n\n### What has changed?\n\n#### Old\n\nOld body.\n' }),
+ tag: '0.92.0',
+ })
+ expect(result.moved).toEqual(['Alpha changes'])
+ expect(result.published.startsWith('---\ntitle: "Breaking Changes"\n---\n\n## 0.92.0\n\n### What has changed?\n\n#### Alpha changes\n')).toBe(true)
+ expect(result.published).toContain('\n\n## 0.91.0\n\n### What has changed?\n\n#### Old\n')
+ expect(result.hidden).toContain('#### Gamma changes')
+ expect(result.hidden).not.toContain('#### Alpha changes')
+ })
+
+ it('appends into an existing version section on a re-run', () => {
+ const result = breakingChangesRollover.rollover({
+ hidden: hiddenPage({ entries: [beta] }),
+ snapshot: hiddenPage({ entries: [beta, alpha] }),
+ published: publishedPage({ sections: '## 0.92.0\n\n### What has changed?\n\n#### Alpha changes\n\nAlpha body.\n\n## 0.91.0\n' }),
+ tag: '0.92.0',
+ })
+ expect(result.moved).toEqual(['`AP_BETA` is removed'])
+ expect(result.published.split('## 0.92.0').length).toBe(2)
+ expect(result.published).toContain('### What has changed?\n\n#### `AP_BETA` is removed\n')
+ expect(result.published.indexOf('#### `AP_BETA` is removed')).toBeLessThan(result.published.indexOf('#### Alpha changes'))
+ })
+
+ it('leaves entries merged after the tag on the hidden page', () => {
+ const result = breakingChangesRollover.rollover({
+ hidden: hiddenPage({ entries: [gamma] }),
+ snapshot: hiddenPage({ entries: [alpha] }),
+ published: publishedPage({ sections: '## 0.91.0\n' }),
+ tag: '0.92.0',
+ })
+ expect(result.moved).toEqual([])
+ expect(result.hidden).toBe(hiddenPage({ entries: [gamma] }))
+ expect(result.published).toBe(publishedPage({ sections: '## 0.91.0\n' }))
+ })
+
+ it('is a no-op when the hidden page or the snapshot has no entries', () => {
+ const empty = hiddenPage({ entries: [] })
+ const withAlpha = hiddenPage({ entries: [alpha] })
+ const published = publishedPage({ sections: '## 0.91.0\n' })
+ expect(breakingChangesRollover.rollover({ hidden: empty, snapshot: withAlpha, published, tag: '0.92.0' }).moved).toEqual([])
+ expect(breakingChangesRollover.rollover({ hidden: withAlpha, snapshot: '', published, tag: '0.92.0' }).moved).toEqual([])
+ })
+
+ it('refuses to roll over when two hidden entries share a title', () => {
+ expect(() => breakingChangesRollover.rollover({
+ hidden: hiddenPage({ entries: [alpha, entry({ title: 'Alpha changes', body: 'A different change with the same title.' })] }),
+ snapshot: hiddenPage({ entries: [alpha] }),
+ published: publishedPage({ sections: '## 0.91.0\n' }),
+ tag: '0.92.0',
+ })).toThrow('Duplicate entry titles')
+ })
+
+ it('keeps the intro and heading of the hidden page when the last entry leaves', () => {
+ const result = breakingChangesRollover.rollover({
+ hidden: hiddenPage({ entries: [alpha] }),
+ snapshot: hiddenPage({ entries: [alpha] }),
+ published: publishedPage({ sections: '## 0.91.0\n' }),
+ tag: '0.92.0',
+ })
+ expect(result.hidden).toBe('---\ntitle: "Unreleased breaking changes"\nhidden: true\n---\n\nIntro sentence.\n\n## What has changed?\n')
+ })
+})
+
+describe('parseEntries', () => {
+ it('never treats "What you need to do" as an entry boundary', () => {
+ const parsed = breakingChangesRollover.parseEntries({ text: hiddenPage({ entries: [alpha, beta] }) })
+ expect(parsed.blocks.map((block) => block[0])).toEqual(['#### Alpha changes', '#### `AP_BETA` is removed'])
+ expect(parsed.blocks[0]).toContain('#### What you need to do')
+ expect(parsed.blocks[0][parsed.blocks[0].length - 1]).toBe('Nothing for Alpha changes.')
+ })
+})
diff --git a/tools/scripts/breaking-changes-rollover.ts b/tools/scripts/breaking-changes-rollover.ts
new file mode 100644
index 00000000000..9883317458f
--- /dev/null
+++ b/tools/scripts/breaking-changes-rollover.ts
@@ -0,0 +1,164 @@
+import { execSync } from 'child_process'
+import { readFileSync, writeFileSync } from 'fs'
+
+function isEntryHeading({ line }: { line: string }): boolean {
+ return line.startsWith('#### ') && !line.startsWith('#### What you need to do')
+}
+
+function trimTrailingBlanks({ lines }: { lines: string[] }): string[] {
+ const copy = [...lines]
+ while (copy.length > 0 && copy[copy.length - 1].trim() === '') {
+ copy.pop()
+ }
+ return copy
+}
+
+function parseEntries({ text }: { text: string }): ParsedPage {
+ const lines = text.split('\n')
+ const firstEntry = lines.findIndex((line) => isEntryHeading({ line }))
+ if (firstEntry === -1) {
+ return { preamble: trimTrailingBlanks({ lines }), blocks: [] }
+ }
+ const blocks: string[][] = []
+ for (const line of lines.slice(firstEntry)) {
+ if (isEntryHeading({ line })) {
+ blocks.push([line])
+ continue
+ }
+ blocks[blocks.length - 1].push(line)
+ }
+ return {
+ preamble: trimTrailingBlanks({ lines: lines.slice(0, firstEntry) }),
+ blocks: blocks.map((block) => trimTrailingBlanks({ lines: block })),
+ }
+}
+
+function joinBlocks({ blocks }: { blocks: string[][] }): string[] {
+ return blocks.flatMap((block, index) => (index === 0 ? block : ['', ...block]))
+}
+
+function renderHidden({ preamble, blocks }: ParsedPage): string {
+ const body = blocks.length === 0 ? [] : ['', ...joinBlocks({ blocks })]
+ return [...preamble, ...body, ''].join('\n')
+}
+
+function insertUnderVersion({ published, tag, blocks }: { published: string, tag: string, blocks: string[][] }): string {
+ const lines = published.split('\n')
+ const heading = `## ${tag}`
+ const existing = lines.indexOf(heading)
+ if (existing !== -1) {
+ let at = existing + 1
+ while (at < lines.length && (lines[at].trim() === '' || lines[at].startsWith('### What has changed?'))) {
+ at += 1
+ }
+ return [...lines.slice(0, at), ...joinBlocks({ blocks }), '', ...lines.slice(at)].join('\n')
+ }
+ const frontmatterEnd = lines.indexOf('---', 1)
+ const at = frontmatterEnd + 1
+ const section = ['', heading, '', '### What has changed?', '', ...joinBlocks({ blocks })]
+ return [...lines.slice(0, at), ...section, ...lines.slice(at)].join('\n')
+}
+
+function duplicateTitles({ blocks }: { blocks: string[][] }): string[] {
+ const seen = new Set<string>()
+ const duplicates = new Set<string>()
+ for (const block of blocks) {
+ const title = block[0].trim()
+ if (seen.has(title)) {
+ duplicates.add(title)
+ }
+ seen.add(title)
+ }
+ return [...duplicates]
+}
+
+function rollover({ hidden, snapshot, published, tag }: RolloverParams): RolloverResult {
+ const current = parseEntries({ text: hidden })
+ const duplicates = duplicateTitles({ blocks: current.blocks })
+ if (duplicates.length > 0) {
+ throw new Error(`Duplicate entry titles on ${UNRELEASED_DOC}; make them unique before releasing: ${duplicates.join(' | ')}`)
+ }
+ const shipped = new Set(parseEntries({ text: snapshot }).blocks.map((block) => block[0].trim()))
+ const moving = current.blocks.filter((block) => shipped.has(block[0].trim()))
+ if (moving.length === 0) {
+ return { hidden, published, moved: [] }
+ }
+ const staying = current.blocks.filter((block) => !shipped.has(block[0].trim()))
+ return {
+ hidden: renderHidden({ preamble: current.preamble, blocks: staying }),
+ published: insertUnderVersion({ published, tag, blocks: moving }),
+ moved: moving.map((block) => block[0].slice(5).trim()),
+ }
+}
+
+function readSnapshot({ tag }: { tag: string }): string {
+ try {
+ return execSync(`git show ${tag}:${UNRELEASED_DOC}`, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] })
+ }
+ catch {
+ return ''
+ }
+}
+
+function main(): void {
+ const tag = process.argv[2]
+ const dryRun = process.argv.includes('--dry-run')
+ if (!tag) {
+ console.error('usage: bun tools/scripts/breaking-changes-rollover.ts <tag> [--dry-run]')
+ process.exit(1)
+ }
+ if (/-rc\./.test(tag)) {
+ console.log(`${tag} is a release candidate, nothing to roll over.`)
+ return
+ }
+ const snapshot = readSnapshot({ tag })
+ if (snapshot === '') {
+ console.log(`No ${UNRELEASED_DOC} at ${tag}, nothing to roll over.`)
+ return
+ }
+ const result = rollover({
+ hidden: readFileSync(UNRELEASED_DOC, 'utf-8'),
+ snapshot,
+ published: readFileSync(PUBLISHED_DOC, 'utf-8'),
+ tag,
+ })
+ if (result.moved.length === 0) {
+ console.log(`No unreleased entry is contained in ${tag}.`)
+ return
+ }
+ for (const title of result.moved) {
+ console.log(`${dryRun ? 'would move' : 'moved'} under ## ${tag}: ${title}`)
+ }
+ if (dryRun) {
+ return
+ }
+ writeFileSync(UNRELEASED_DOC, result.hidden)
+ writeFileSync(PUBLISHED_DOC, result.published)
+}
+
+export const breakingChangesRollover = { parseEntries, rollover }
+
+export const UNRELEASED_DOC = 'docs/install/reference/breaking-changes-unreleased.mdx'
+export const PUBLISHED_DOC = 'docs/install/reference/breaking-changes.mdx'
+
+type ParsedPage = {
+ preamble: string[]
+ blocks: string[][]
+}
+
+type RolloverParams = {
+ hidden: string
+ snapshot: string
+ published: string
+ tag: string
+}
+
+type RolloverResult = {
+ hidden: string
+ published: string
+ moved: string[]
+}
+
+if (import.meta.main) {
+ main()
+}