@ferrflow/doc 7.29.0 → 7.30.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (87) hide show
  1. package/changelog/2026-04-24-ferrflow-changelog-ordering.md +11 -0
  2. package/changelog/2026-04-28-ferrflow-editorial-hero.md +11 -0
  3. package/changelog/2026-04-29-ferrflow-docs-claude-style.md +22 -0
  4. package/changelog/2026-04-29-ferrflow-editorial-body.md +16 -0
  5. package/changelog/2026-04-29-ferrflow-v4-2-prerelease-channels.md +27 -0
  6. package/changelog/2026-05-05-ferrflow-do-not-track-and-first-run-notice.md +22 -0
  7. package/changelog/2026-06-07-ferrflow-bot-release-rulesets.md +29 -0
  8. package/changelog/2026-06-16-ferrflow-declarative-publishers.md +40 -0
  9. package/changelog/2026-06-25-ferrflow-jobs-flag.md +24 -0
  10. package/changelog/2026-06-25-ferrflow-publish-tag-scope.md +35 -0
  11. package/changelog/2026-06-26-ferrflow-arm-targets.md +24 -0
  12. package/changelog/2026-07-13-ferrflow-hook-points.md +32 -0
  13. package/changelog/2026-07-16-ferrflow-migrate-semantic-release.md +41 -0
  14. package/changelog/2026-07-17-ferrflow-linked-fixed-groups.md +23 -0
  15. package/changelog/2026-07-17-ferrflow-telemetry-removed.md +14 -0
  16. package/changelog/2026-07-18-ferrflow-bitbucket.md +20 -0
  17. package/changelog/2026-07-18-ferrflow-breaking-change-variants.md +20 -0
  18. package/changelog/2026-07-18-ferrflow-commit-graph.md +14 -0
  19. package/changelog/2026-07-18-ferrflow-doctor.md +21 -0
  20. package/changelog/2026-07-18-ferrflow-schema-subcommand.md +19 -0
  21. package/changelog/2026-07-18-ferrflow-selfhosted-forge-autodetect.md +19 -0
  22. package/changelog/2026-07-20-ferrflow-hook-all-packages.md +32 -0
  23. package/changelog/2026-07-20-ferrflow-rich-hook-context.md +35 -0
  24. package/changelog/2026-07-21-ferrflow-diff-command.md +20 -0
  25. package/changelog/2026-07-21-ferrflow-hook-release-url.md +27 -0
  26. package/changelog/2026-07-21-ferrflow-hosted-api.md +26 -0
  27. package/changelog/2026-07-21-ferrflow-migrate-js-yaml.md +19 -0
  28. package/changelog/2026-07-21-ferrflow-migrate-more-tools.md +24 -0
  29. package/changelog/2026-07-21-ferrflow-persistent-release-pr.md +17 -0
  30. package/changelog/2026-07-25-ferrflow-concurrent-release-replan.md +14 -0
  31. package/changelog/2026-07-27-ferrflow-cabal-cmake-formats.md +23 -0
  32. package/changelog/2026-07-27-ferrflow-cosign-bundles.md +25 -0
  33. package/changelog/2026-07-27-ferrflow-tags-before-releases.md +14 -0
  34. package/changelog/2026-07-28-ferrflow-changesets-workspace-discovery.md +17 -0
  35. package/changelog/2026-08-04-ferrflow-diff-package-scope.md +21 -0
  36. package/changelog/2026-08-05-ferrflow-api-own-domain.md +25 -0
  37. package/changelog/2026-08-07-ferrflow-action-input-hardening.md +18 -0
  38. package/changelog/2026-08-07-ferrflow-mit-license.md +26 -0
  39. package/changelog/2026-08-07-ferrflow-verified-installs.md +28 -0
  40. package/changelog/2026-08-10-ferrflow-commit-formats.md +46 -0
  41. package/changelog/2026-08-15-ferrflow-lockfile-refresh.md +16 -0
  42. package/changelog/2026-08-20-ferrflow-version-source-option.md +29 -0
  43. package/changelog/2026-08-20-ferrflow-version-source.md +23 -0
  44. package/changelog/2026-08-25-ferrflow-bot-verified-commits.md +19 -0
  45. package/changelog/2026-08-25-ferrflow-config-include.md +30 -0
  46. package/changelog/2026-08-25-ferrflow-pr-mode-tags-on-merge.md +21 -0
  47. package/changelog/2026-08-25-ferrflow-push-error-classification.md +24 -0
  48. package/changelog/2026-08-27-ferrflow-rollback.md +27 -0
  49. package/changelog/2026-08-27-ferrflow-workspace-defaults.md +34 -0
  50. package/changelog/2026-08-28-ferrflow-annotated-tag-deref.md +26 -0
  51. package/changelog/2026-08-28-ferrflow-cache-staleness.md +19 -0
  52. package/changelog/2026-08-28-ferrflow-cargo-publish-url.md +28 -0
  53. package/changelog/2026-08-28-ferrflow-npm-publish-url.md +27 -0
  54. package/changelog/2026-08-28-ferrflow-panic-cleanup.md +19 -0
  55. package/changelog/2026-08-29-ferrflow-calver-short-seq.md +31 -0
  56. package/changelog/2026-08-29-ferrflow-scoped-package-commits.md +23 -0
  57. package/changelog/2026-09-01-ferrflow-cascade-strongest-bump.md +25 -0
  58. package/changelog/2026-09-01-ferrflow-changelog-hook-rewrite.md +21 -0
  59. package/changelog/2026-09-01-ferrflow-doctor-lockfile.md +36 -0
  60. package/changelog/2026-09-01-ferrflow-graph-impact.md +34 -0
  61. package/changelog/2026-09-01-ferrflow-own-bump-raised.md +25 -0
  62. package/changelog/2026-09-02-ferrflow-galaxyyml.md +25 -0
  63. package/changelog/2026-09-03-ferrflow-docs-public.md +17 -0
  64. package/changelog/2026-09-04-ferrflow-build-metadata.md +27 -0
  65. package/changelog/2026-09-22-ferrflow-package-schema.md +31 -0
  66. package/changelog/2026-09-22-ferrflow-push-token-per-forge.md +23 -0
  67. package/changelog/2026-09-22-ferrflow-release-git-identity.md +18 -0
  68. package/changelog/2026-09-23-ferrflow-release-mr-title-length.md +21 -0
  69. package/changelog/2026-09-24-ferrflow-selector-padding.md +19 -0
  70. package/changelog/2026-09-24-ferrflow-template-leading-v.md +19 -0
  71. package/changelog/2026-09-24-ferrflow-template-literals.md +21 -0
  72. package/changelog/2026-09-28-ferrflow-floating-tag-backward.md +12 -0
  73. package/changelog/2026-09-28-ferrflow-helm-chart-name.md +12 -0
  74. package/changelog/2026-09-28-ferrflow-migrate-tag-template.md +23 -0
  75. package/changelog/2026-09-28-ferrflow-padded-versions.md +12 -0
  76. package/changelog/2026-10-02-ferrflow-shadow-release.md +17 -0
  77. package/changelog/2026-10-03-ferrflow-latest-tag-hotfix.md +13 -0
  78. package/changelog/2026-10-03-ferrflow-pr-lookup-branch-encoding.md +12 -0
  79. package/changelog/2026-10-03-ferrflow-preview-backtick.md +12 -0
  80. package/changelog/2026-10-03-ferrflow-why-doctor-wording.md +10 -0
  81. package/changelog/2026-10-07-ferrflow-strategy-names-json.md +12 -0
  82. package/changelog/2026-10-10-ferrflow-hook-timeout.md +23 -0
  83. package/changelog/2026-10-10-ferrflow-init-workspace-discovery.md +16 -0
  84. package/data/benchmarks.json +683 -683
  85. package/docs-en/reference/cli.md +2 -0
  86. package/docs-fr/reference/cli.md +2 -0
  87. package/package.json +1 -1
@@ -0,0 +1,27 @@
1
+ ---
2
+ title: 'FerrFlow: Post-publish hooks get the release URL'
3
+ summary: '`postPublish` hooks now receive `releaseUrl` (the URL of the GitHub/GitLab release FerrFlow just created), so you can link to it from a Slack notification, a dashboard, or a downstream job.'
4
+ date: 2026-07-21T08:00:00Z
5
+ product: ferrflow
6
+ type: new
7
+ prLink: https://github.com/FerrLabs/FerrFlow/pull/743
8
+ docsLink: https://ferrflow.com/docs/configuration/config-file
9
+ ---
10
+
11
+ A `postPublish` hook knew the version and tag, but not where the release actually landed. To announce a release with a link, you had to reconstruct the URL by hand.
12
+
13
+ FerrFlow now hands it to you. Once the forge release is created, `postPublish` hooks receive `releaseUrl`: the canonical URL of the GitHub or GitLab release for that package's tag. Shell hooks read `FERRFLOW_RELEASE_URL`; JS/TS function hooks get `ctx.releaseUrl`.
14
+
15
+ ```js
16
+ export default {
17
+ workspace: {
18
+ hooks: {
19
+ postPublish(ctx) {
20
+ if (ctx.releaseUrl) notify(`${ctx.package}@${ctx.newVersion} → ${ctx.releaseUrl}`);
21
+ },
22
+ },
23
+ },
24
+ };
25
+ ```
26
+
27
+ It's `null` wherever the URL isn't known yet: at `prePublish` (the release isn't created until after), on `--dry-run`, and when no forge is configured.
@@ -0,0 +1,26 @@
1
+ ---
2
+ title: 'FerrFlow: Hosted API for validate, preview, schema and releases'
3
+ summary: 'A new hosted API at api.ferrlabs.com/v1/ferrflow/* lets you validate a config, preview version bumps and changelog, fetch the config JSON Schema, and resolve the latest release over HTTP, with results identical to the CLI.'
4
+ date: 2026-07-21T16:00:00Z
5
+ product: ferrflow
6
+ type: new
7
+ prLink: https://github.com/FerrLabs/FerrLabs-Cloud/pull/668
8
+ docsLink: https://ferrflow.com/docs/reference/api
9
+ ---
10
+
11
+ Some things are easier over HTTP than by shelling out to the CLI: a web validator, an editor integration, a PR-preview comment, a "is there a newer version?" check. FerrFlow now exposes a small hosted API for exactly those, under `https://api.ferrlabs.com/v1/ferrflow/*`. Every endpoint is public (no auth) and safe to call from CI, an editor, or a browser.
12
+
13
+ The important part: `validate` and `preview` run the **same FerrFlow core the CLI runs**, so their results are identical to `ferrflow validate` and `ferrflow check`. There's no second implementation to drift out of sync.
14
+
15
+ ```bash
16
+ # Preview the bump + changelog for a set of commits, no repo needed
17
+ curl -X POST https://api.ferrlabs.com/v1/ferrflow/preview \
18
+ -H 'content-type: application/json' \
19
+ -d '{
20
+ "config": "{\"package\":[{\"name\":\"api\",\"path\":\".\"}]}",
21
+ "commits": [{ "message": "feat(api): add endpoint" }],
22
+ "current_versions": { "api": "1.2.3" }
23
+ }'
24
+ ```
25
+
26
+ The full set: `POST /validate` (hosted config validation), `POST /preview` (bump + changelog), `GET /schema` (the config JSON Schema, straight from the source of truth: point your editor's `$schema` at it), `GET /latest` (latest release + per-platform download and signature URLs), and `GET /health`. The machine-readable contract lives at `/v1/ferrflow/openapi.json`. See the [API reference](https://ferrflow.com/docs/reference/api) for every endpoint.
@@ -0,0 +1,19 @@
1
+ ---
2
+ title: 'FerrFlow: Migrate reads JS and YAML configs'
3
+ summary: '`ferrflow migrate` now imports JavaScript and YAML release configs directly (`.releaserc.js`, `release.config.js`, `.releaserc.yaml`, `.versionrc.js`, and friends), not just JSON, so you no longer have to hand-convert your config before migrating.'
4
+ date: 2026-07-21T14:00:00Z
5
+ product: ferrflow
6
+ type: new
7
+ prLink: https://github.com/FerrLabs/FerrFlow/pull/750
8
+ docsLink: https://ferrflow.com/docs/reference/cli
9
+ ---
10
+
11
+ Plenty of semantic-release and standard-version setups keep their config in JavaScript (`release.config.js`) or YAML (`.releaserc.yaml`) rather than JSON. `ferrflow migrate` used to read JSON only and told you to convert the rest by hand first.
12
+
13
+ Now it reads them directly. A JavaScript config is evaluated with `node`, which imports the config, resolves it if it's a function, and reads the result, the same way FerrFlow already runs your `ferrflow.js` config, locally against your own repo. A YAML config is parsed straight through. Both then feed the existing converters, so the mapping and the mapped/ignored/review report are identical to the JSON path.
14
+
15
+ ```bash
16
+ ferrflow migrate # auto-detects .releaserc.js, .releaserc.yaml, release.config.js, …
17
+ ```
18
+
19
+ JavaScript configs need Node.js on your PATH; if it's missing, the error says so.
@@ -0,0 +1,24 @@
1
+ ---
2
+ title: 'FerrFlow: Migrate from changesets, release-please & standard-version'
3
+ summary: '`ferrflow migrate` now imports configs from changesets, release-please, and standard-version too (not just semantic-release), generating an equivalent `ferrflow.json` and a report of what mapped, what was ignored, and what needs a look.'
4
+ date: 2026-07-21T13:00:00Z
5
+ product: ferrflow
6
+ type: new
7
+ prLink: https://github.com/FerrLabs/FerrFlow/pull/745
8
+ docsLink: https://ferrflow.com/docs/reference/cli
9
+ ---
10
+
11
+ Switching to FerrFlow shouldn't mean rewriting your release config by hand. `ferrflow migrate` reads your existing release tool's config and writes the equivalent `ferrflow.json`. It already understood semantic-release; now it covers the other three big ones too.
12
+
13
+ - **release-please** (`release-please-config.json`): the `packages` map becomes FerrFlow packages, each package's `release-type` picks the right version file (Cargo.toml, package.json, pyproject.toml, Chart.yaml, …), `include-component-in-tag` becomes a `tagTemplate`, and the PR flow becomes `releaseCommitMode: pr`.
14
+ - **standard-version** (`.versionrc`): `tagPrefix` becomes a `tagTemplate` and `bumpFiles` / `packageFiles` become `versionedFiles`.
15
+ - **changesets** (`.changeset/config.json`): `baseBranch` becomes `branch`, and `linked` / `fixed` become version groups.
16
+
17
+ It auto-detects the source, or you can force it with `--from release-please`. Every run prints what mapped, what it ignored, and what needs manual review. Nothing is silently guessed. For changesets it also flags the one thing that matters: changesets versions from `.changeset/*.md` files, while FerrFlow versions from conventional commits.
18
+
19
+ ```bash
20
+ ferrflow migrate # auto-detect
21
+ ferrflow migrate --from standard-version
22
+ ```
23
+
24
+ Then review the generated config and run `ferrflow validate`.
@@ -0,0 +1,17 @@
1
+ ---
2
+ title: 'FerrFlow: One persistent release PR'
3
+ summary: 'In `releaseCommitMode: pr`, FerrFlow now keeps a single long-lived release pull request and updates it on each new commit, instead of opening a fresh PR (and leaving a stale one) every time the version changes.'
4
+ date: 2026-07-21T10:00:00Z
5
+ product: ferrflow
6
+ type: new
7
+ prLink: https://github.com/FerrLabs/FerrFlow/pull/744
8
+ docsLink: https://ferrflow.com/docs/configuration/config-file
9
+ ---
10
+
11
+ `releaseCommitMode: pr` opens your version bump and changelog as a pull request instead of committing straight to the branch. Until now that PR was tied to the version it was opened for, so a second `feat:` landing before you merged spawned a _new_ PR and left the first one stale. You'd end up with a pile of `v1.3.0`, `v1.4.0`, … release PRs to clean up.
12
+
13
+ Now it's one PR. FerrFlow keeps a single release branch per target (`ferrflow/release-<target-branch>`), and on every new commit it recomputes the version and changelog and force-pushes that same branch, so the open PR's title and body update in place. This is the release-please / Changesets model.
14
+
15
+ `autoMergeReleases` (default `true`) re-enables auto-merge on each update, and is a no-op when off: the PR just waits for a human. PR mode works on GitHub and GitLab.
16
+
17
+ It also won't stomp on your work: if you push a commit onto the release branch yourself (a review fix, say), FerrFlow notices it isn't a `chore(release):` commit, warns, and leaves the branch and PR untouched for that run rather than force-pushing over it.
@@ -0,0 +1,14 @@
1
+ ---
2
+ title: 'FerrFlow: Concurrent releases no longer fail with E2006'
3
+ summary: 'When two release runs race, the losing run now replans against the version the winner published instead of aborting with E2006, and no longer silently drops the other packages it was about to release.'
4
+ date: 2026-07-25T10:00:00Z
5
+ product: ferrflow
6
+ type: fix
7
+ prLink: https://github.com/FerrLabs/FerrFlow/pull/766
8
+ ---
9
+
10
+ On an active repo, merging a few PRs in quick succession triggers near-simultaneous release runs. One of them could fail with `error[E2006]: Tag(s) already exist on remote pointing to a different commit`, and the message suggested deleting the divergent tag or re-running with `--force`. Both were wrong here: the tag belonged to a concurrent run's perfectly valid release, so either remedy would have destroyed or overwritten a published version.
11
+
12
+ The run rebased its release commit onto the new remote tip but kept the version plan it had computed *before* rebasing, so it still tried to create a tag another run had already taken. Worse, the failure aborted the whole run: a second package with unreleased changes was left unreleased with no signal beyond the failed job.
13
+
14
+ A losing run now resets to the remote tip and recomputes its plan against the winner's history. The bump is applied on top of whatever was just published, so a fix planned as `1.0.1` becomes `1.1.1` if a concurrent run shipped `1.1.0` in the meantime. It never lands below the latest release. Every package in the run is replanned together, so nothing is dropped. E2006 is now reserved for genuine divergence, which makes its "delete the divergent remote tag" advice correct when it does appear.
@@ -0,0 +1,23 @@
1
+ ---
2
+ title: 'FerrFlow: Cabal and CMake version files'
3
+ summary: 'FerrFlow now bumps the version in Haskell `*.cabal` files and in the `project()` call of a `CMakeLists.txt`, bringing the supported formats to 16.'
4
+ date: 2026-07-27T14:00:00Z
5
+ product: ferrflow
6
+ type: new
7
+ prLink: https://github.com/FerrLabs/FerrFlow/pull/773
8
+ docsLink: https://ferrflow.com/docs/configuration/formats
9
+ ---
10
+
11
+ Two ecosystems that kept coming up are now first-class: Haskell and CMake-based C/C++. Point a versioned file at them and FerrFlow bumps them like any other format, rewriting only the version span so the rest of the file keeps its layout and comments.
12
+
13
+ ```toml
14
+ [[package.versioned_files]]
15
+ path = "my-package.cabal"
16
+ format = "cabal"
17
+
18
+ [[package.versioned_files]]
19
+ path = "CMakeLists.txt"
20
+ format = "cmake"
21
+ ```
22
+
23
+ Both formats are careful about the version-shaped things sitting next to the one you actually want. In a `.cabal` file, `cabal-version:` declares which Cabal feature set the file uses (bumping it would change how the file is parsed), so only the top-level `version:` field is touched, and indented `version:` fields inside stanzas are left alone. In CMake, FerrFlow updates the `VERSION` argument of `project()`, including the multi-line form, while `cmake_minimum_required(VERSION …)` and any `set(<name>_VERSION …)` variable stay untouched.
@@ -0,0 +1,25 @@
1
+ ---
2
+ title: 'FerrFlow: Releases are signed with a single Sigstore bundle'
3
+ summary: 'From v5.48.0 each release artifact ships one `.bundle` instead of a separate `.sig` and `.crt`. Verification is one flag shorter; older releases keep working as before.'
4
+ date: 2026-07-27T20:00:00Z
5
+ product: ferrflow
6
+ type: breaking
7
+ prLink: https://github.com/FerrLabs/FerrFlow/pull/774
8
+ docsLink: https://ferrflow.com/docs/verifying-releases
9
+ ---
10
+
11
+ Sigstore's tooling moved on: cosign v3 replaced the separate signature and certificate outputs with a single bundle that carries both. FerrFlow releases follow suit. Every artifact (the platform tarballs and zips, the completions archive, the SBOM) now ships one `<artifact>.bundle` sidecar instead of a `.sig` + `.crt` pair.
12
+
13
+ Verification loses a flag:
14
+
15
+ ```bash
16
+ cosign verify-blob \
17
+ --bundle ferrflow-linux-x64.tar.gz.bundle \
18
+ --certificate-identity-regexp "https://github.com/FerrLabs/FerrFlow/.*" \
19
+ --certificate-oidc-issuer https://token.actions.githubusercontent.com \
20
+ ferrflow-linux-x64.tar.gz
21
+ ```
22
+
23
+ **If you verify releases in CI, this is the change to make.** A pipeline that downloads `<artifact>.sig` and `<artifact>.crt` will fail on v5.48.0 and later, because those files are no longer published. Releases up to **v5.47.4** are untouched and still verify with `--certificate` and `--signature`. Nothing was removed retroactively.
24
+
25
+ The hosted API follows the same rule: `GET /v1/ferrflow/latest` now returns `bundle_url` for releases that have one, and keeps returning `signature_url` and `cert_url` for the older releases that carry them, so a client can simply use whichever field is present.
@@ -0,0 +1,14 @@
1
+ ---
2
+ title: 'FerrFlow: Tags are pushed before releases are published'
3
+ summary: 'A release run now pushes its tags to the remote before creating the GitHub or Gitea release, so a failure in between can no longer leave a published release pointing at a tag that never landed, and annotated tag messages are no longer silently replaced.'
4
+ date: 2026-07-27T10:00:00Z
5
+ product: ferrflow
6
+ type: fix
7
+ prLink: https://github.com/FerrLabs/FerrFlow/pull/771
8
+ ---
9
+
10
+ A release run used to create the forge releases first and push the annotated tags afterwards. Any failure in between (a network blip, branch protection, a tag a concurrent run had just taken) left the forge ahead of git: releases published against a ref the remote did not have.
11
+
12
+ On GitHub and Gitea it also cost you the tag message. FerrFlow sent the release with a target commit, so for a tag that did not exist yet those APIs created it themselves, as a *lightweight* tag. The annotated tag FerrFlow had built (the one carrying the changelog body) was pushed a moment later, pointed at the same commit, and was therefore treated as already synced and skipped. The lightweight tag was what survived.
13
+
14
+ Tags now land first, and the release is created against a ref that provably exists. FerrFlow no longer sends a target commit at all, so the forge can't invent tags behind git's back, and `git show <tag>` returns the release notes as intended. Pushing and publishing are also separate resume points now: if release creation fails, re-running retries only that step instead of replaying the push.
@@ -0,0 +1,17 @@
1
+ ---
2
+ title: 'FerrFlow: Migrating from changesets now finds your packages'
3
+ summary: '`ferrflow migrate --from changesets` reads your workspace globs and scaffolds one package entry per workspace package, instead of a single root package you had to expand by hand.'
4
+ date: 2026-07-28T14:00:00Z
5
+ product: ferrflow
6
+ type: new
7
+ prLink: https://github.com/FerrLabs/FerrFlow/pull/775
8
+ docsLink: https://ferrflow.com/docs/reference/cli
9
+ ---
10
+
11
+ changesets is a monorepo tool, so migrating from it used to end with the least useful part done by hand: FerrFlow scaffolded a single root package and asked you to list every workspace package yourself. On a repo with thirty packages that's thirty entries to write before anything runs.
12
+
13
+ The migration now reads the same workspace declaration changesets does (`workspaces` in `package.json`, both the array and the yarn-berry `{ packages: [...] }` form, and `packages:` in `pnpm-workspace.yaml`), expands the globs, and writes one `package` entry per discovered package, each pointing at its own `package.json` and `CHANGELOG.md`.
14
+
15
+ The practical win is in the version groups. `linked` and `fixed` name packages by npm name, and those names now match packages that actually exist in the generated config, so it passes `ferrflow validate` straight out of the migration. If a group names something outside the workspace, the migration report says which one rather than leaving you to find out at validation time.
16
+
17
+ Dependency directories are skipped, so a `node_modules` full of manifests is never mistaken for your workspace. A repo without a workspace declaration still gets a single root package, as before.
@@ -0,0 +1,21 @@
1
+ ---
2
+ title: 'FerrFlow: `diff` now shows only the package you asked about'
3
+ summary: 'In a monorepo, `ferrflow diff <package> <from>..<to>` filters the range to commits that touched that package, so its commit list and changelog match what a release would actually produce.'
4
+ date: 2026-08-04T10:00:00Z
5
+ product: ferrflow
6
+ type: fix
7
+ prLink: https://github.com/FerrLabs/FerrFlow/pull/781
8
+ docsLink: https://ferrflow.com/docs/reference/cli
9
+ ---
10
+
11
+ `ferrflow diff` compares two tags and shows you what changed between them. In a monorepo it was showing the raw git range: every commit between the two tags, including the ones that only touched other packages. Asking about your API and being told it shipped a frontend redesign is worse than not asking.
12
+
13
+ The range is now scoped by path: a commit counts if it touched the package's `path` or one of its `sharedPaths`. That is what the commit list, the breaking-change list and the generated changelog are built from, which is the whole point of previewing it.
14
+
15
+ This entry first said the scoping matched what `ferrflow release` produced. It did not. `release` went on collecting every commit since the package's last tag until that was fixed on 2026-08-29. Between the two dates the preview and the release disagreed, and the preview was the accurate one.
16
+
17
+ ```bash
18
+ ferrflow diff api api@v1.0.0..api@v1.1.0
19
+ ```
20
+
21
+ Shared paths still count, so a change to a `proto/` directory listed in the API's `sharedPaths` shows up under the API, as it should. Single-package repositories are unaffected. They own every commit, and nothing is filtered. `--json` output is scoped identically.
@@ -0,0 +1,25 @@
1
+ ---
2
+ title: 'FerrFlow: the hosted API moves to api.ferrflow.com'
3
+ summary: 'The FerrFlow API and the hosted bot token exchange now answer on api.ferrflow.com. The old api.ferrlabs.com host keeps working indefinitely.'
4
+ date: 2026-08-05T10:00:00Z
5
+ product: ferrflow
6
+ type: new
7
+ prLink: https://github.com/FerrLabs/FerrFlow-Cloud/pull/772
8
+ docsLink: https://ferrflow.com/docs/reference/api
9
+ ---
10
+
11
+ The hosted FerrFlow API (`validate`, `preview`, `latest`, the config schema, and the bot token exchange) was published under the holding company's hostname, `api.ferrlabs.com`. Pointing a `$schema` at a *ferrlabs* URL to validate a *ferrflow* config never read right, and every other product already serves its API from its own domain. It now answers on `api.ferrflow.com`, which is the host the documentation uses from here on.
12
+
13
+ Paths are unchanged, so moving over is a hostname swap and nothing else:
14
+
15
+ ```bash
16
+ curl "https://api.ferrflow.com/v1/ferrflow/latest?platform=linux-x64"
17
+ ```
18
+
19
+ ```json
20
+ { "$schema": "https://api.ferrflow.com/v1/ferrflow/schema" }
21
+ ```
22
+
23
+ **Nothing breaks.** `api.ferrlabs.com/v1/ferrflow/*` reaches exactly the same endpoints and will keep doing so indefinitely. It is the same service behind a second hostname, not a redirect and not a deprecation. FerrFlow versions already released have the old endpoint compiled in and continue to work untouched; new versions of the CLI and the GitHub Action exchange their bot token on the new host. If you override the endpoint yourself, `bot_endpoint:` on the Action and `FERRFLOW_BOT_ENDPOINT` in the CLI still take precedence.
24
+
25
+ One thing that deliberately did **not** move: the OIDC audience stays `ferrflow.ferrlabs.com`. It is the identifier your runner mints the token for, not a URL, and the service validates against that exact string.
@@ -0,0 +1,18 @@
1
+ ---
2
+ title: 'FerrFlow: the Action no longer interpolates its inputs into shell'
3
+ summary: 'force_version, package and version reached the Action’s run scripts as raw shell source. They now arrive as environment variables and are validated before use.'
4
+ date: 2026-08-07T09:00:00Z
5
+ product: ferrflow
6
+ type: security
7
+ prLink: https://github.com/FerrLabs/FerrFlow/pull/810
8
+ ---
9
+
10
+ The FerrFlow GitHub Action built three of its shell steps with `${{ }}` interpolation, which substitutes a value into the script *before* the shell parses it. Any workflow that wired `force_version`, `package` or `version` from data it did not control (an issue title, a `workflow_dispatch` input, a matrix value derived from a pull request) could therefore have had that data executed as shell, in a job that by design holds a repository write token.
11
+
12
+ All three inputs now reach the step as environment variables, are quoted at every use, and are checked before they are passed on: `version` must be `latest` or a semver triple, `force_version` must be `VERSION` or `NAME@VERSION`, and each entry in `package` must look like a package name. Anything else fails the step with a clear message instead of running.
13
+
14
+ Arguments are assembled into an array and passed as `ferrflow "${args[@]}"`, so a value containing spaces or shell metacharacters is one inert argument rather than parsed source.
15
+
16
+ **What you need to do:** nothing beyond moving to a current version of the Action. No input changed name, shape or meaning. If you were passing a value that does not match the formats above (a version string with unusual characters, for instance), the step will now tell you rather than silently doing something else.
17
+
18
+ Also fixed in the same change: `mode: publish` did not forward the `bot` inputs, so `bot: true` combined with `mode: publish` silently ran without the hosted bot token.
@@ -0,0 +1,26 @@
1
+ ---
2
+ title: 'FerrFlow: now MIT licensed'
3
+ summary: 'FerrFlow moves from MPL-2.0 to MIT. Fewer obligations for everyone using it; the change ships as v6, so Action pins move from @v5 to @v6.'
4
+ date: 2026-08-07T10:00:00Z
5
+ product: ferrflow
6
+ type: breaking
7
+ prLink: https://github.com/FerrLabs/FerrFlow/pull/813
8
+ ---
9
+
10
+ FerrFlow is now distributed under the MIT licence instead of MPL-2.0. This applies to the CLI, the Rust library published on crates.io, the `ferrflow` npm package and its platform binaries, and the WASM build.
11
+
12
+ MPL-2.0 is weak copyleft: modify a FerrFlow source file and you had to publish that file. In practice that obligation almost never applied (FerrFlow is invoked, not linked), but it was enough to route the tool into legal review at organisations whose dependency policy allowlists MIT, BSD and Apache and flags everything else. That review always ended in approval, and always cost weeks. MIT removes the question.
13
+
14
+ **Nothing is taken away.** Every right you had under MPL-2.0 you still have under MIT, plus the file-level reciprocity obligation is gone. Releases up to 5.52.x remain available under MPL-2.0 in perpetuity if you have a reason to prefer them.
15
+
16
+ **What you need to do:** if you pin the GitHub Action to a floating major tag, move it to `@v6`.
17
+
18
+ ```yaml
19
+ - uses: FerrLabs/FerrFlow@v6
20
+ with:
21
+ bot: true
22
+ ```
23
+
24
+ `v5` stays where it is and will not receive further releases. Nothing else changes: no flags, no config fields, no output formats. The major bump exists so that "which licence?" has a clean answer per major line: v5 and earlier are MPL-2.0, v6 onward is MIT. Pinning a full version (`@v6.0.0`) or a commit SHA is unaffected.
25
+
26
+ If you consume FerrFlow as a Rust library, `cargo update` picks the new licence up with the version; if your build enforces a licence allowlist, MIT should already be on it.
@@ -0,0 +1,28 @@
1
+ ---
2
+ title: 'FerrFlow: the Action verifies the binary it downloads'
3
+ summary: 'Releases now ship a signed SHA256SUMS, and the GitHub Action checks the archive against it (and its build provenance) before extracting anything.'
4
+ date: 2026-08-07T09:30:00Z
5
+ product: ferrflow
6
+ type: security
7
+ prLink: https://github.com/FerrLabs/FerrFlow/pull/811
8
+ ---
9
+
10
+ The FerrFlow Action installed the CLI by piping a release asset straight into `tar`. Nothing checked what came back before it was extracted and run, and it runs holding a repository write token. The release pipeline had been producing cosign signatures and build provenance attestations for a while, but nothing consumed them, and no checksum manifest was published at all.
11
+
12
+ Releases now include a `SHA256SUMS` covering every platform archive. It is generated before the signing steps, so it is itself attested and cosign-signed, and it ships alongside `SHA256SUMS.bundle`.
13
+
14
+ The Action downloads the archive to a temporary directory, verifies its digest against `SHA256SUMS`, and only then extracts. When you pin a specific version it additionally verifies build provenance with `gh attestation verify`: provenance binds to a concrete release, so it cannot be checked against the mutable `latest` URL.
15
+
16
+ **What you need to do:** nothing. This is transparent on a current version of the Action.
17
+
18
+ Two behaviours worth knowing. Releases cut before this change carry no `SHA256SUMS`; the Action warns and continues rather than breaking every workflow pinned to an older version. But a `SHA256SUMS` that exists and has no entry for the archive being installed is a hard failure: otherwise removing one line would be a trivial bypass.
19
+
20
+ You can run the same checks yourself:
21
+
22
+ ```bash
23
+ cosign verify-blob \
24
+ --bundle ferrflow-linux-x64.tar.gz.bundle \
25
+ --certificate-identity-regexp "https://github.com/FerrLabs/FerrFlow/.*" \
26
+ --certificate-oidc-issuer https://token.actions.githubusercontent.com \
27
+ ferrflow-linux-x64.tar.gz
28
+ ```
@@ -0,0 +1,46 @@
1
+ ---
2
+ title: 'FerrFlow: commit formats are configurable, and the defaults are more permissive'
3
+ summary: 'workspace.commitFormats lets you declare which commit subjects map to which bump level. The defaults now also recognise Feat:, Fix/, feature: and friends, which is why this ships as v7.'
4
+ date: 2026-08-10T18:00:00Z
5
+ product: ferrflow
6
+ type: breaking
7
+ prLink: https://github.com/FerrLabs/FerrFlow/pull/824
8
+ docsLink: https://ferrflow.com/docs/configuration/config-file
9
+ ---
10
+
11
+ FerrFlow only ever recognised strict lowercase conventional prefixes. Teams whose history uses `Feat/add-login`, `Fix: resolve crash` or `feature:` (the shapes that come out of branch-named squash merges) got no releases at all, with nothing in the output explaining why.
12
+
13
+ `workspace.commitFormats` now declares the mapping. Each of `major`, `minor` and `patch` takes a pattern, a list of patterns, or `"all"`:
14
+
15
+ ```json
16
+ {
17
+ "workspace": {
18
+ "commitFormats": {
19
+ "minor": ["feat:*", "feat(?*):*", "Feat/*"],
20
+ "patch": "all",
21
+ "caseSensitive": false
22
+ }
23
+ }
24
+ }
25
+ ```
26
+
27
+ `*` matches any run of characters (including `/`, since commit subjects are prose and routinely contain file paths), `?` matches exactly one. Resolution runs major → minor → patch, first match wins. `"all"` is a catch-all, useful for repos that follow no convention at all: `"patch": "all"` releases on every commit while `minor` and `major` patterns still promote the ones that match.
28
+
29
+ **What changes without you doing anything.** The built-in defaults are now permissive: `Feat:`, `Feat/`, `feature:`, `Fix:`, `Fix/`, `Refactor:` and `Refactor/` all trigger releases, alongside the lowercase conventional forms that already did. If your repository has commits in those shapes, they will start producing versions where they previously produced none. That is the breaking part, and the reason this is v7.
30
+
31
+ To keep the old strictness, declare it:
32
+
33
+ ```json
34
+ {
35
+ "workspace": {
36
+ "commitFormats": {
37
+ "minor": ["feat:*", "feat(?*):*"],
38
+ "patch": ["fix:*", "fix(?*):*", "perf:*", "perf(?*):*", "refactor:*", "refactor(?*):*"]
39
+ }
40
+ }
41
+ }
42
+ ```
43
+
44
+ Breaking markers are not configurable and never needed to be: `feat!:`, `fix(api)!:`, the `feat(api!):` typo and a `BREAKING CHANGE:` footer are detected structurally, whatever patterns you set. A glob cannot express them precisely: `*!:*` would match any subject containing `!:` anywhere, turning `fix: handle the !: token in the parser` into a major release.
45
+
46
+ **Action tag:** `v7` is the current floating major. Update `uses: FerrLabs/FerrFlow@v6` to `@v7`; `v6` will not receive further releases.
@@ -0,0 +1,16 @@
1
+ ---
2
+ title: 'FerrFlow: lockfiles no longer go stale after a release'
3
+ summary: 'updateLockfiles could leave Cargo.lock at the previous version while the release still reported success. Both causes are fixed: the crate name is read from the manifest, and a cold registry cache no longer defeats the update.'
4
+ date: 2026-08-15T10:00:00Z
5
+ product: ferrflow
6
+ type: fix
7
+ prLink: https://github.com/FerrLabs/FerrFlow/pull/844
8
+ ---
9
+
10
+ If you set `updateLockfiles: true`, FerrFlow could bump `Cargo.toml` and leave `Cargo.lock` pointing at the previous version. Nothing failed: the update error was logged as a warning, the release finished green, and the drift surfaced later as a dirty working tree or a lockfile check in CI.
11
+
12
+ There were two separate causes. FerrFlow ran `cargo update -p <name>` with the package name from your config, which is not the cargo crate name: a package called `api` holding a crate called `my-app-api` produced `package ID specification 'api' did not match any packages`. FerrFlow now reads the real crate name from the manifest it is versioning, so the two can differ freely. Separately, the update ran with `--offline`, which cannot resolve dependencies when the cargo registry cache is empty. That is the normal state of a release job that checks out and installs the toolchain without building, and it made the failure look intermittent: the same repo would update its lock on a warm runner and skip it on a cold one.
13
+
14
+ `--offline` is still tried first, because it is faster and works with no network and no private-registry credentials. When it fails, FerrFlow retries once without it.
15
+
16
+ Nothing to change on your side. If a lockfile drifted while this was broken, commit it once and releases will keep it in sync from here.
@@ -0,0 +1,29 @@
1
+ ---
2
+ title: 'FerrFlow: choose whether the tag or the file is the source of truth'
3
+ summary: 'When a package has both a git tag and a version in a versioned file, FerrFlow took whichever was higher. That is still the default, and versionSource now lets a repo say the tags are the record, or that the file is.'
4
+ date: 2026-08-20T12:00:00Z
5
+ product: ferrflow
6
+ type: new
7
+ prLink: https://github.com/FerrLabs/FerrFlow/pull/873
8
+ docsLink: https://ferrflow.com/docs/configuration/config-file/
9
+ ---
10
+
11
+ FerrFlow resolves the version it starts from by looking at two places: the highest tag reachable from HEAD, and the version written in the package's first versioned file. When both exist it took whichever was higher. That is a good default and remains the default, but it has a cost worth naming: a mistake in either source only ever ratchets upward. A bad merge that resurrects an old `version =` line, a hand-edit, a generator writing a future date into a manifest, and FerrFlow releases from the inflated number with nothing to walk it back.
12
+
13
+ The reverse case is just as real, which is why this is a choice rather than a fix. Moving a package between repositories carries its manifest across while the tags stay behind, and there the file is the honest source.
14
+
15
+ `versionSource` lets a repo say which one it trusts:
16
+
17
+ ```jsonc
18
+ {
19
+ "workspace": {
20
+ "versionSource": "highest" // default, unchanged
21
+ // "tag" - the tags are the record of what shipped, ignore the file
22
+ // "file" - the file is the source, ignore the tag
23
+ }
24
+ }
25
+ ```
26
+
27
+ It can be set per package too, so a monorepo migrating one package does not have to flip the policy for the rest. With only one source present the setting has no effect, and neither does it change how the version is then bumped.
28
+
29
+ Nothing changes if you upgrade without touching your config. The release and check output now says which source a version came from and whether it won on height or because you configured it, so you can tell whether your repo needs the option at all before reaching for it.
@@ -0,0 +1,23 @@
1
+ ---
2
+ title: 'FerrFlow: release output says where the current version came from'
3
+ summary: 'The version FerrFlow starts from is resolved from a tag, a versioned file, or neither. The release and check output now names the source, so a package whose tag was never pushed is distinguishable from one that has no tags yet.'
4
+ date: 2026-08-20T10:00:00Z
5
+ product: ferrflow
6
+ type: new
7
+ prLink: https://github.com/FerrLabs/FerrFlow/pull/870
8
+ docsLink: https://ferrflow.com/docs/reference/cli
9
+ ---
10
+
11
+ FerrFlow resolves the version it starts from in one of four ways: the highest tag reachable from HEAD, the version written in the package's first versioned file, the higher of the two when both exist, or the strategy's starting point when neither does. Until now all four printed the same bare number, so four different situations were indistinguishable from the output.
12
+
13
+ That hides a real failure: a version that looks right for the wrong reason. A package whose tag was never pushed reads its version from the file and releases as if nothing were wrong, and a first release looks identical to a package that has simply lost its tags. Answering "where did that number come from" meant reading the source.
14
+
15
+ The release and check lines now name the source:
16
+
17
+ ```
18
+ ● discord 2026.8.18 → 2026.8.19 (calverseq, from discord/Cargo.toml)
19
+ ● discord 2026.8.18 → 2026.8.19 (calverseq, from discord/Cargo.toml, over tag v2026.8.1)
20
+ ● api 0.0.0 → 0.1.0 (minor, bootstrapped)
21
+ ```
22
+
23
+ The same information is in `release --json` and `check --json` as a `version_source` object, tagged with a `kind` of `tag`, `file`, `tag_over_file`, `file_over_tag`, or `bootstrap`, so CI can branch on it without parsing prose. The field is additive and optional, and nothing about how versions are resolved has changed: only how much of that resolution you can see.
@@ -0,0 +1,19 @@
1
+ ---
2
+ title: 'FerrFlow: release commits from the bot now show as verified'
3
+ summary: 'Commits authored by ferrflow[bot] showed as unverified, and no signing key could fix it because a GitHub App cannot register one. With bot: true on GitHub, the release commit is now authored through GitHub itself, which signs it.'
4
+ date: 2026-08-25T18:00:00Z
5
+ product: ferrflow
6
+ type: new
7
+ prLink: https://github.com/FerrLabs/FerrFlow/pull/941
8
+ docsLink: https://ferrflow.com/docs/configuration/github-action/
9
+ ---
10
+
11
+ Release commits made under `bot: true` carried the `ferrflow[bot]` identity but showed as unverified in the GitHub UI, sitting next to everyone else's verified work. There was no configuration that fixed it: GitHub Apps have no setting for a GPG or SSH key, so there was no key for FerrFlow to sign with. The alternative, shipping a signing key into every user's CI, is exactly what you do not want a release tool to ask of you.
12
+
13
+ GitHub offers the way out. A commit created through its `createCommitOnBranch` API is signed by GitHub and marked verified, and an App can use it to author commits in its own name. No private key exists anywhere in the chain. With `bot: true` on a GitHub repository, FerrFlow now creates the release commit that way instead of through local git, in both `commit` and `pr` modes.
14
+
15
+ One condition comes with it, and it shapes the result. GitHub signs a bot's commit only when the request carries no custom author, committer or signature information. So the commit is attributed to `ferrflow[bot]` and to nothing else. There is no version of this where FerrFlow sets a custom author and still gets the verified mark.
16
+
17
+ Nothing changes anywhere else. Without `bot: true`, or on GitLab, Gitea, Forgejo and Bitbucket, the commit is built by local git exactly as before. If you want verified commits under your own identity rather than the bot's, set `commit.gpgsign` and FerrFlow honours it on every forge and on both commit paths.
18
+
19
+ Worth knowing: annotated tags are still created and pushed by git, so they are not covered by this. Only the commit is signed.
@@ -0,0 +1,30 @@
1
+ ---
2
+ title: 'FerrFlow: one config file per package'
3
+ summary: 'A monorepo no longer has to declare every package in a single root config. The new include key points at per-package files, each owning its own settings, and a package path inside one of those files defaults to its directory.'
4
+ date: 2026-08-25T12:00:00Z
5
+ product: ferrflow
6
+ type: new
7
+ prLink: https://github.com/FerrLabs/FerrFlow/pull/932
8
+ docsLink: https://ferrflow.com/docs/configuration/config-file/
9
+ ---
10
+
11
+ FerrFlow looked for its config at the repository root and nowhere else, so a monorepo with twenty packages carried one long file that every team edited. The usual consequences followed: merge conflicts on an unrelated package's block, no way to give a project ownership of its own release settings through `CODEOWNERS`, and a file long enough that nobody reads it before changing it.
12
+
13
+ The `include` key splits it up. The root config keeps the workspace-level settings and points at the per-package files:
14
+
15
+ ```json
16
+ {
17
+ "workspace": { "versioning": "semver" },
18
+ "include": ["projects/*/ferrflow.json"]
19
+ }
20
+ ```
21
+
22
+ Each included file describes one package, using the same keys as a `package` entry:
23
+
24
+ ```json
25
+ { "name": "api", "dependsOn": ["core"] }
26
+ ```
27
+
28
+ Paths inside an included file are relative to that file, and `path` defaults to its directory. The example above needs no `path` at all: `projects/api/ferrflow.json` describes the package in `projects/api`, and renaming or moving that directory requires no edit. Dependencies still refer to packages by name, so `dependsOn` works across files and the release order comes out of the same graph as before. Included files may use a different format than the root config, and they can sit alongside an inline `package` array while a repo migrates.
29
+
30
+ Four situations are rejected rather than quietly ignored: an `include` pattern that matches no file, two packages sharing a name, an included file that declares `workspace`, `include`, or `package`, and one that resolves to a path outside the repository. Each of them would otherwise have produced a run that did nothing and exited successfully, which on a release tool is how a team discovers weeks later that nothing shipped.
@@ -0,0 +1,21 @@
1
+ ---
2
+ title: 'FerrFlow: release PRs are tagged when they merge, not when they open'
3
+ summary: 'In pr mode FerrFlow tagged and published the moment it opened the release PR, on the commit before the version bump. The PR then reported nothing left to release and was never updated again. Tagging now happens after the merge, on the commit that carries the bump.'
4
+ date: 2026-08-25T16:00:00Z
5
+ product: ferrflow
6
+ type: fix
7
+ prLink: https://github.com/FerrLabs/FerrFlow/pull/936
8
+ docsLink: https://ferrflow.com/docs/configuration/config-file/
9
+ ---
10
+
11
+ `releaseCommitMode: "pr"` is meant to propose a release and let a human accept it. It did not work that way. The run that opened the pull request also pushed the tags and published the GitHub releases, on the current tip of the target branch, which is the commit *before* the version bump. The bump itself lived on the PR branch and was tagged by nothing.
12
+
13
+ Two things followed from that. A tag such as `v1.1.0` pointed at a tree whose version files still declared `1.0.0`. And because the versions were already tagged, every later run reported "Nothing to release", so the release PR was never regenerated: it froze at the version it was opened with and quietly stopped tracking the branch. If the PR was never merged, the tags and releases were public anyway, for a release that never happened.
14
+
15
+ `pr` mode now runs in the two phases it always described. The proposing run computes the bump, writes the version files and changelog onto the release branch, and opens or updates the PR, without creating a single tag. Every new commit on the target branch regenerates that branch, so the open PR keeps showing the version that would ship right now. The finalising run happens after the merge: FerrFlow finds the `chore(release):` commit on the target branch, sees that the versions it carries have no tags, and tags exactly those before publishing the releases.
16
+
17
+ The versions are read from the version files rather than recomputed, which matters more than it sounds. Simply not tagging early would have left the merged release PR looking like fresh unreleased work, so the next run would have proposed another bump on top, and no version would ever have been tagged. Squash merges and merge commits both work, and re-running after a successful release does nothing.
18
+
19
+ One limit is worth stating: a package declared without `versionedFiles` has no version to read on the target branch, so it is not finalised this way. Use `commit` mode for tag-only packages.
20
+
21
+ Repositories already using `pr` mode are not repaired by the upgrade. Their existing tags sit one commit behind the bump, and any release published for a PR that never merged is still there. Both need removing by hand before the next clean release.
@@ -0,0 +1,24 @@
1
+ ---
2
+ title: 'FerrFlow: a failed push now says what actually went wrong'
3
+ summary: 'Every push failure was reported as "pushed onto a stale branch" and answered by regenerating the release commit three times, whatever the real cause. Transient server errors are now retried where they belong, real races are detected by their actual wording, and permanent failures surface immediately.'
4
+ date: 2026-08-25T17:00:00Z
5
+ product: ferrflow
6
+ type: fix
7
+ prLink: https://github.com/FerrLabs/FerrFlow/pull/937
8
+ docsLink: https://ferrflow.com/docs/reference/errors/
9
+ ---
10
+
11
+ When a release could not push, FerrFlow said this, three times, before giving up:
12
+
13
+ ```
14
+ Release attempt 1/3 pushed onto a stale 'main': E2004: Failed to push branch 'main'
15
+ Resetting working tree to remote tip and regenerating the release commit against the latest history…
16
+ ```
17
+
18
+ It said that whatever had happened. The check behind the message matched `E2004`, the generic "push failed" code that rides on every push error, so a GitHub server hiccup, an expired token and a genuine race all produced the same diagnosis. Anyone reading the log went looking for a concurrent push that had never occurred, and a permanent failure such as a revoked permission burned all three attempts before revealing its real cause.
19
+
20
+ Two things now decide separately. A transient server-side failure is recognised as such and retried with backoff by the push layer, which is what that layer exists for and where a hiccup is usually resolved on the second attempt. Anything that is neither transient nor a race surfaces immediately with the message git actually produced, no retries and no misleading claim about the branch being stale.
21
+
22
+ Races themselves are now detected by what git actually says, which turned out to matter more than expected. The old wording list looked for `non-fast-forward`, but git only says that once you have fetched. Push without fetching first, which is what a release job does, and git says `fetch first` instead. That case had been reaching the retry path through the generic code rather than on its own merit, so tightening the check meant covering it properly, along with `stale info` and the divergent-remote-tag case.
23
+
24
+ Nothing to change in your configuration. Release logs get more specific, transient failures stop costing you a release, and permanent ones stop pretending to be something else.
@@ -0,0 +1,27 @@
1
+ ---
2
+ title: 'FerrFlow: undo a release that failed partway'
3
+ summary: 'A release that dies after pushing tags used to leave you reconstructing what it did from a job log, then deleting refs by hand. ferrflow rollback reads the checkpoint that run left behind and undoes exactly what it did, refusing the parts that cannot be undone.'
4
+ date: 2026-08-27T12:00:00Z
5
+ product: ferrflow
6
+ type: new
7
+ prLink: https://github.com/FerrLabs/FerrFlow/pull/946
8
+ docsLink: https://ferrflow.com/docs/cli/rollback/
9
+ ---
10
+
11
+ Releases fail in the middle. A registry answers 401, a docker build breaks, a hook aborts. By then the tags are pushed and the release commit is on the branch, and FerrFlow could only go forward: a checkpoint let you resume, never rewind. Getting back to a clean state meant working out which tags the run had pushed, deleting each one, removing the forge releases by hand, reverting the commit and repairing the manifest. On a monorepo with a cascade that is a lot of state to reconstruct from a job log, under time pressure.
12
+
13
+ `ferrflow rollback` does it from the checkpoint instead of from memory:
14
+
15
+ ```bash
16
+ ferrflow rollback # prints the plan, changes nothing
17
+ ferrflow rollback --yes # applies it
18
+ ferrflow rollback --yes api web
19
+ ```
20
+
21
+ The dry run is the default, since the destructive form deletes remote refs.
22
+
23
+ What makes it safe is mostly what it refuses to do. It never deletes a tag that has moved: every tag is recorded with the commit it pointed at, and one that no longer matches is reported and skipped, because a rollback can happen long after the failure and a tag someone else recreated is not that run's to remove.
24
+
25
+ It also stops on any package already published to a registry that cannot be unpublished. crates.io and PyPI keep every version forever, and npm refuses to republish an unpublished one, so deleting the tag would strand a version anyone can still install. Rollback says so and leaves that package alone; the right answer is a new patch version. Docker tags, Helm charts, release assets and webhooks are replaceable and block nothing. In a monorepo where one package published and three did not, the three roll back and the one is refused, rather than half of each being undone.
26
+
27
+ The release commit is reverted only when the whole run rolls back with nothing blocked, because that commit carries every package's version bump and reverting it while one package stays released would quietly undo that package's version too. The revert is left for you to push: rollback has just deleted remote refs, and forcing a branch update on top of that is a decision worth taking with the branch in front of you.