@ferrflow/doc 7.29.0 → 7.30.0
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.
- package/changelog/2026-04-24-ferrflow-changelog-ordering.md +11 -0
- package/changelog/2026-04-28-ferrflow-editorial-hero.md +11 -0
- package/changelog/2026-04-29-ferrflow-docs-claude-style.md +22 -0
- package/changelog/2026-04-29-ferrflow-editorial-body.md +16 -0
- package/changelog/2026-04-29-ferrflow-v4-2-prerelease-channels.md +27 -0
- package/changelog/2026-05-05-ferrflow-do-not-track-and-first-run-notice.md +22 -0
- package/changelog/2026-06-07-ferrflow-bot-release-rulesets.md +29 -0
- package/changelog/2026-06-16-ferrflow-declarative-publishers.md +40 -0
- package/changelog/2026-06-25-ferrflow-jobs-flag.md +24 -0
- package/changelog/2026-06-25-ferrflow-publish-tag-scope.md +35 -0
- package/changelog/2026-06-26-ferrflow-arm-targets.md +24 -0
- package/changelog/2026-07-13-ferrflow-hook-points.md +32 -0
- package/changelog/2026-07-16-ferrflow-migrate-semantic-release.md +41 -0
- package/changelog/2026-07-17-ferrflow-linked-fixed-groups.md +23 -0
- package/changelog/2026-07-17-ferrflow-telemetry-removed.md +14 -0
- package/changelog/2026-07-18-ferrflow-bitbucket.md +20 -0
- package/changelog/2026-07-18-ferrflow-breaking-change-variants.md +20 -0
- package/changelog/2026-07-18-ferrflow-commit-graph.md +14 -0
- package/changelog/2026-07-18-ferrflow-doctor.md +21 -0
- package/changelog/2026-07-18-ferrflow-schema-subcommand.md +19 -0
- package/changelog/2026-07-18-ferrflow-selfhosted-forge-autodetect.md +19 -0
- package/changelog/2026-07-20-ferrflow-hook-all-packages.md +32 -0
- package/changelog/2026-07-20-ferrflow-rich-hook-context.md +35 -0
- package/changelog/2026-07-21-ferrflow-diff-command.md +20 -0
- package/changelog/2026-07-21-ferrflow-hook-release-url.md +27 -0
- package/changelog/2026-07-21-ferrflow-hosted-api.md +26 -0
- package/changelog/2026-07-21-ferrflow-migrate-js-yaml.md +19 -0
- package/changelog/2026-07-21-ferrflow-migrate-more-tools.md +24 -0
- package/changelog/2026-07-21-ferrflow-persistent-release-pr.md +17 -0
- package/changelog/2026-07-25-ferrflow-concurrent-release-replan.md +14 -0
- package/changelog/2026-07-27-ferrflow-cabal-cmake-formats.md +23 -0
- package/changelog/2026-07-27-ferrflow-cosign-bundles.md +25 -0
- package/changelog/2026-07-27-ferrflow-tags-before-releases.md +14 -0
- package/changelog/2026-07-28-ferrflow-changesets-workspace-discovery.md +17 -0
- package/changelog/2026-08-04-ferrflow-diff-package-scope.md +21 -0
- package/changelog/2026-08-05-ferrflow-api-own-domain.md +25 -0
- package/changelog/2026-08-07-ferrflow-action-input-hardening.md +18 -0
- package/changelog/2026-08-07-ferrflow-mit-license.md +26 -0
- package/changelog/2026-08-07-ferrflow-verified-installs.md +28 -0
- package/changelog/2026-08-10-ferrflow-commit-formats.md +46 -0
- package/changelog/2026-08-15-ferrflow-lockfile-refresh.md +16 -0
- package/changelog/2026-08-20-ferrflow-version-source-option.md +29 -0
- package/changelog/2026-08-20-ferrflow-version-source.md +23 -0
- package/changelog/2026-08-25-ferrflow-bot-verified-commits.md +19 -0
- package/changelog/2026-08-25-ferrflow-config-include.md +30 -0
- package/changelog/2026-08-25-ferrflow-pr-mode-tags-on-merge.md +21 -0
- package/changelog/2026-08-25-ferrflow-push-error-classification.md +24 -0
- package/changelog/2026-08-27-ferrflow-rollback.md +27 -0
- package/changelog/2026-08-27-ferrflow-workspace-defaults.md +34 -0
- package/changelog/2026-08-28-ferrflow-annotated-tag-deref.md +26 -0
- package/changelog/2026-08-28-ferrflow-cache-staleness.md +19 -0
- package/changelog/2026-08-28-ferrflow-cargo-publish-url.md +28 -0
- package/changelog/2026-08-28-ferrflow-npm-publish-url.md +27 -0
- package/changelog/2026-08-28-ferrflow-panic-cleanup.md +19 -0
- package/changelog/2026-08-29-ferrflow-calver-short-seq.md +31 -0
- package/changelog/2026-08-29-ferrflow-scoped-package-commits.md +23 -0
- package/changelog/2026-09-01-ferrflow-cascade-strongest-bump.md +25 -0
- package/changelog/2026-09-01-ferrflow-changelog-hook-rewrite.md +21 -0
- package/changelog/2026-09-01-ferrflow-doctor-lockfile.md +36 -0
- package/changelog/2026-09-01-ferrflow-graph-impact.md +34 -0
- package/changelog/2026-09-01-ferrflow-own-bump-raised.md +25 -0
- package/changelog/2026-09-02-ferrflow-galaxyyml.md +25 -0
- package/changelog/2026-09-03-ferrflow-docs-public.md +17 -0
- package/changelog/2026-09-04-ferrflow-build-metadata.md +27 -0
- package/changelog/2026-09-22-ferrflow-package-schema.md +31 -0
- package/changelog/2026-09-22-ferrflow-push-token-per-forge.md +23 -0
- package/changelog/2026-09-22-ferrflow-release-git-identity.md +18 -0
- package/changelog/2026-09-23-ferrflow-release-mr-title-length.md +21 -0
- package/changelog/2026-09-24-ferrflow-selector-padding.md +19 -0
- package/changelog/2026-09-24-ferrflow-template-leading-v.md +19 -0
- package/changelog/2026-09-24-ferrflow-template-literals.md +21 -0
- package/changelog/2026-09-28-ferrflow-floating-tag-backward.md +12 -0
- package/changelog/2026-09-28-ferrflow-helm-chart-name.md +12 -0
- package/changelog/2026-09-28-ferrflow-migrate-tag-template.md +23 -0
- package/changelog/2026-09-28-ferrflow-padded-versions.md +12 -0
- package/changelog/2026-10-02-ferrflow-shadow-release.md +17 -0
- package/changelog/2026-10-03-ferrflow-latest-tag-hotfix.md +13 -0
- package/changelog/2026-10-03-ferrflow-pr-lookup-branch-encoding.md +12 -0
- package/changelog/2026-10-03-ferrflow-preview-backtick.md +12 -0
- package/changelog/2026-10-03-ferrflow-why-doctor-wording.md +10 -0
- package/changelog/2026-10-07-ferrflow-strategy-names-json.md +12 -0
- package/changelog/2026-10-10-ferrflow-hook-timeout.md +23 -0
- package/changelog/2026-10-10-ferrflow-init-workspace-discovery.md +16 -0
- package/data/benchmarks.json +707 -707
- package/docs-en/reference/cli.md +2 -0
- package/docs-fr/reference/cli.md +2 -0
- package/package.json +1 -1
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 'FerrFlow: a config without a workspace block now keeps its defaults'
|
|
3
|
+
summary: 'Omitting the workspace block from a config file silently dropped every workspace default. The remote became an empty string and the release failed at the push; the target branch became empty and said nothing at all.'
|
|
4
|
+
date: 2026-08-27T10:00:00Z
|
|
5
|
+
product: ferrflow
|
|
6
|
+
type: fix
|
|
7
|
+
prLink: https://github.com/FerrLabs/FerrFlow/pull/945
|
|
8
|
+
docsLink: https://ferrflow.com/docs/configuration/config-file/
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
The `workspace` block is optional, and a config that leaves it out is the shape most people write first:
|
|
12
|
+
|
|
13
|
+
```json
|
|
14
|
+
{
|
|
15
|
+
"package": [
|
|
16
|
+
{ "name": "app", "path": ".", "versionedFiles": [{ "path": "Cargo.toml", "format": "toml" }] }
|
|
17
|
+
]
|
|
18
|
+
}
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
That config lost every workspace default. The failure people would actually hit came at the very end of a release, after the version bump, the changelog and the tag had all been written:
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
error[E2004]: Failed to push branch ''
|
|
25
|
+
Remote '' has no URL
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Writing `"workspace": {}` behaved correctly, and omitting the key did not, which is not a distinction anyone would expect to matter.
|
|
29
|
+
|
|
30
|
+
The cause was two sets of defaults that disagreed. Each field declared its own fallback for the case where the block is present but the key is missing, while an entirely absent block took a different path that filled everything with empty values. Only the second path was reachable from a minimal config, and only the first was tested.
|
|
31
|
+
|
|
32
|
+
The empty remote was the loud symptom. The quieter ones mattered more: the target branch, normally detected from `origin/HEAD` and falling back to `main`, became an empty string that then fed tag lookup and the release branch name without complaint, and auto-merge for release pull requests silently turned itself off despite being documented as on.
|
|
33
|
+
|
|
34
|
+
Both paths now produce the same values. Nothing to change in your configuration, and a config that already carried a `workspace` block was never affected.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 'FerrFlow: an annotated tag already on the remote no longer blocks the push'
|
|
3
|
+
summary: 'FerrFlow compared the commit a tag points at against the tag object itself, so any annotated tag already on the remote looked like it had moved. The push failed with a message about a difference that was not there, telling you to delete a perfectly healthy tag.'
|
|
4
|
+
date: 2026-08-28T10:00:00Z
|
|
5
|
+
product: ferrflow
|
|
6
|
+
type: fix
|
|
7
|
+
prLink: https://github.com/FerrLabs/FerrFlow/pull/955
|
|
8
|
+
docsLink: https://ferrflow.com/docs/reference/errors/
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
FerrFlow checks the remote before pushing tags, so that a tag someone else already put there at a different commit stops the release instead of being silently overwritten. The check compared the wrong pair of values.
|
|
12
|
+
|
|
13
|
+
An annotated tag is two objects: the tag itself, carrying its message, and the commit it points at. FerrFlow read the commit locally and the tag object remotely, then compared them. They are never equal, so any annotated tag already on the remote was reported as diverged:
|
|
14
|
+
|
|
15
|
+
```
|
|
16
|
+
E2006: Tag(s) already exist on remote pointing to a different commit:
|
|
17
|
+
v1.0.0 (local ebf8a82 != remote ffed861)
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Both refer to the same tag at the same commit. The message names a commit difference that does not exist, and advises deleting a tag that is fine.
|
|
21
|
+
|
|
22
|
+
FerrFlow creates annotated tags, so this was the ordinary case rather than an edge one. It stayed hidden because the release planner normally skips a package whose tag already exists, so the push is never attempted. The gap opened when the local view of tags was stale while the remote had the tag, most plausibly after a failed tag fetch at the start of a release, whose error was not surfaced.
|
|
23
|
+
|
|
24
|
+
The cause was one refspec. Asking `git ls-remote` for `refs/tags/<tag>` does not return the `refs/tags/<tag>^{}` entry that carries the commit, so the dereferencing step had nothing to work with. FerrFlow now asks for both. Lightweight tags were never affected, since for them the tag and the commit are the same object, which is also why every existing test in this area missed it.
|
|
25
|
+
|
|
26
|
+
Nothing to change on your side. A genuinely divergent tag still stops the release, with the same message, which now means what it says.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 'FerrFlow: check no longer serves a stale plan after an uncommitted edit'
|
|
3
|
+
summary: 'The cache behind ferrflow check keyed on the commit, the tags and the config, but not on the version files it actually reads. Editing a version without committing returned the previous answer for up to five minutes. Interrupted runs also left temp files that nothing ever cleaned up.'
|
|
4
|
+
date: 2026-08-28T16:00:00Z
|
|
5
|
+
product: ferrflow
|
|
6
|
+
type: fix
|
|
7
|
+
prLink: https://github.com/FerrLabs/FerrFlow/pull/963
|
|
8
|
+
docsLink: https://ferrflow.com/docs/cli/check/
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
`ferrflow check` caches its result for five minutes so repeated previews are instant. The cache key was built from the commit, the tag refs and the config file, which covers everything `check` reads from git. It does not cover everything `check` reads.
|
|
12
|
+
|
|
13
|
+
To render `1.0.0 → 1.1.0`, `check` opens the version files on disk. Change one without committing, by hand or through a `release` that wrote files before failing, and none of the three parts of the key move. The old answer came straight back, presented exactly like a fresh one. A wrong answer delivered confidently is worse than a slow one, which is the whole reason to fix a five-minute window on a preview command.
|
|
14
|
+
|
|
15
|
+
The key now includes the contents of every configured version file. We hashed contents rather than timestamps and sizes: `1.0.0` and `1.1.0` are the same length, so size alone misses precisely the edit this is meant to catch, and file timestamps are too coarse on some filesystems to be trusted for it. Reading a few small manifests costs far less than the history walk the cache is there to avoid.
|
|
16
|
+
|
|
17
|
+
Separately, the cache writes each entry to a temporary file and renames it into place. A run killed between those two steps, a cancelled CI job or a panic, left the temporary file behind, and the cleanup pass only ever looked at finished entries. On a repository with a lot of interrupted runs, `.git/ferrflow-cache/` grew without bound. Leftovers older than an hour are now cleaned up alongside everything else, while a file a write may still be using is left alone.
|
|
18
|
+
|
|
19
|
+
Nothing to change on your side. Both fixes are internal to the cache, and `ferrflow cache clear` still empties it outright.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 'FerrFlow: the crates.io link after a publish points at your crate again'
|
|
3
|
+
summary: 'FerrFlow built the crates.io link from the package name in its own config rather than the one in Cargo.toml. A workspace routinely uses short names against prefixed crates, and short crate names are long since taken, so the link led to an unrelated crate instead of yours.'
|
|
4
|
+
date: 2026-08-28T15:00:00Z
|
|
5
|
+
product: ferrflow
|
|
6
|
+
type: fix
|
|
7
|
+
prLink: https://github.com/FerrLabs/FerrFlow/pull/962
|
|
8
|
+
docsLink: https://ferrflow.com/docs/configuration/publishers/
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
After publishing to a registry, FerrFlow prints a link to the released version. For cargo it built that link from the package name in your FerrFlow config, not from `[package].name` in the manifest cargo actually publishes under.
|
|
12
|
+
|
|
13
|
+
In a workspace those routinely differ, because the config keeps short names while the crates carry a prefix:
|
|
14
|
+
|
|
15
|
+
```json
|
|
16
|
+
{ "name": "bridge", "path": "crates/bridge", "publishers": [{ "kind": "cargo" }] }
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
```toml
|
|
20
|
+
[package]
|
|
21
|
+
name = "idlewarden-bridge"
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
That produced `crates.io/crates/bridge/26.8.27` instead of `crates.io/crates/idlewarden-bridge/26.8.27`. Short crate names have been taken for years, so the link resolved to a real, unrelated crate rather than returning a 404. A log line pointing at somebody else's project as if it were the release that just went out is worse than a missing link, and it is the sort of thing that gets pasted into a release announcement.
|
|
25
|
+
|
|
26
|
+
FerrFlow now reads the name from `Cargo.toml`, and falls back to the config name when the manifest cannot be read or carries no `[package]` table. The "already exists on the registry" message uses the real name for the same reason: it makes a claim about the registry, so it has to name the crate the registry knows. Messages about which of your packages failed keep the config name, since that is the one you would look for in your config.
|
|
27
|
+
|
|
28
|
+
The publish itself was never affected. `cargo publish` runs in the package directory and cargo reads the manifest itself, so the right crate was always uploaded. This follows the same fix for the npm publisher, where a short config name against a scoped package name caused the identical problem.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 'FerrFlow: the npm link after a publish points at your package again'
|
|
3
|
+
summary: 'FerrFlow built the npmjs.com link from the package name in its own config rather than the one in package.json. In a monorepo those differ by default, and the short names are all taken on npm, so the link led to a stranger''s package instead of yours.'
|
|
4
|
+
date: 2026-08-28T14:00:00Z
|
|
5
|
+
product: ferrflow
|
|
6
|
+
type: fix
|
|
7
|
+
prLink: https://github.com/FerrLabs/FerrFlow/pull/961
|
|
8
|
+
docsLink: https://ferrflow.com/docs/configuration/publishers/
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
After publishing to npm, FerrFlow prints a link to the released version. It built that link from the package name in your FerrFlow config, not from the `name` field npm actually publishes under.
|
|
12
|
+
|
|
13
|
+
In a monorepo those are rarely the same. The usual shape is a short name in the config and a scoped name in the manifest:
|
|
14
|
+
|
|
15
|
+
```json
|
|
16
|
+
{ "name": "site", "path": "site", "versionedFiles": [{ "path": "site/package.json", "format": "json" }] }
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
```json
|
|
20
|
+
{ "name": "@acme/site" }
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
That produced `npmjs.com/package/site` instead of `npmjs.com/package/@acme/site`. And because short names like `site`, `api` and `core` are long since taken on npm, the link resolved to somebody else's package rather than returning a 404, which is the kind of wrong that goes unnoticed for a while.
|
|
24
|
+
|
|
25
|
+
FerrFlow now reads the name from `package.json`, and falls back to the config name when the manifest cannot be read. The "already exists on the registry" message uses the real name too, for the same reason: it makes a claim about what is on npm, so it has to name the package npm knows.
|
|
26
|
+
|
|
27
|
+
The publish itself was never affected. `npm publish` runs inside the package directory and npm reads the manifest itself, so the right thing was always uploaded. Only what FerrFlow printed afterwards was wrong.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 'FerrFlow: a crash no longer leaves the release lock or a registry token behind'
|
|
3
|
+
summary: 'The release binary is built to abort on panic, which skips the cleanup that runs when a release ends normally. A crash left the lock file in place, blocking the repository for half an hour, and could leave a scoped npm token on disk.'
|
|
4
|
+
date: 2026-08-28T18:00:00Z
|
|
5
|
+
product: ferrflow
|
|
6
|
+
type: fix
|
|
7
|
+
prLink: https://github.com/FerrLabs/FerrFlow/pull/964
|
|
8
|
+
docsLink: https://ferrflow.com/docs/cli/release/
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
FerrFlow takes a lock while a release runs, so two releases cannot start at once in the same repository, and writes a temporary npm config when a registry needs a token. Both are removed when the run ends, whether it succeeded or failed.
|
|
12
|
+
|
|
13
|
+
Neither was removed when the process crashed. The release binary is compiled to abort immediately on a panic rather than unwind, a deliberate choice that cuts the binary by about a quarter, and aborting skips the cleanup step that normally runs as each value goes out of scope. The consequence had not been followed through.
|
|
14
|
+
|
|
15
|
+
So a crash mid-release left the lock file in place. The next release refused to start, and since a stale lock is only taken over after a timeout, the repository stayed blocked for half an hour with nothing explaining why. A crash during an npm publish could likewise leave a file containing a registry token in the system temporary directory until the operating system got around to clearing it.
|
|
16
|
+
|
|
17
|
+
FerrFlow now keeps a list of files that must not outlive the process and removes them from a panic handler, which does still run when the binary aborts. The normal path is unchanged: whatever was already cleaned up is taken off the list rather than deleted twice.
|
|
18
|
+
|
|
19
|
+
One gap remains, and it is worth knowing about: interrupting a local release with Ctrl-C still leaves the lock behind, for the same underlying reason. Handling that needs machinery we did not want to add without weighing it separately. If it happens, `ferrflow release --force-unlock` takes the lock back immediately.
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 'FerrFlow: calver-short-seq, and a warning when a release is held back'
|
|
3
|
+
summary: 'A date-only version scheme can only publish once a day, and the second attempt was indistinguishable from having nothing to release. FerrFlow now says so out loud, and calver-short-seq gives the compact year a sequence counter.'
|
|
4
|
+
date: 2026-08-29T10:00:00Z
|
|
5
|
+
product: ferrflow
|
|
6
|
+
type: new
|
|
7
|
+
prLink: https://github.com/FerrLabs/FerrFlow/pull/967
|
|
8
|
+
docsLink: https://ferrflow.com/docs/configuration/versioning-strategies/
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
A version made only of a date can be produced once a day, by definition. Under `calver-short`, the second release of the day recomputes the same `YY.M.D`, the version does not move, and FerrFlow declines to publish. That part is inherent to the scheme rather than a defect.
|
|
12
|
+
|
|
13
|
+
What was a defect is that it looked exactly like having nothing to release. Both printed "Nothing to release", so a merged fix could sit unpublished until the next day with nobody told. The only way to notice was to find later that a deployed image was missing a change that had been merged hours earlier.
|
|
14
|
+
|
|
15
|
+
FerrFlow now names it:
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
! app has releasable commits but stays at 26.8.29, so nothing was published
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
That line appears whenever there is releasable work and the strategy produces the version that is already out, whatever the strategy. It is worth having even for repositories that never hit the daily limit, since the same silence covered any misconfiguration that froze the version.
|
|
22
|
+
|
|
23
|
+
The other half is a way out. `calver-seq` already pairs the full year with a counter, `YYYY.M.SEQ`, but there was no equivalent for the compact year, so a repository on `calver-short` had nowhere to go at constant format. `calver-short-seq` fills that in with `YY.M.SEQ`:
|
|
24
|
+
|
|
25
|
+
```json
|
|
26
|
+
{ "workspace": { "versioning": "calver-short-seq" } }
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Switching to it costs nothing in version continuity, which is the reason to prefer it over `calver-seq` here. The counter picks up from whatever the last release was, so a repository whose most recent version was `26.8.29` gets `26.8.30` next, then `26.8.31` the same day. Moving to `calver-seq` instead would work, but it jumps the leading number from `26` to `2026`, which is irreversible and makes the year ambiguous when reading older tags alongside newer ones.
|
|
30
|
+
|
|
31
|
+
Set the strategy explicitly if you use it. `YY.M.SEQ` and `YY.M.D` are the same shape, and a value like `26.8.29` is a plausible day as well as a plausible counter, so tag detection cannot tell them apart on its own.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 'FerrFlow: a package release no longer carries other packages'' commits'
|
|
3
|
+
summary: 'In a monorepo, each package collected every commit since its own last tag, whatever those commits touched. That padded the changelog with other packages'' work and, less visibly, let their commits decide the version bump.'
|
|
4
|
+
date: 2026-08-29T12:00:00Z
|
|
5
|
+
product: ferrflow
|
|
6
|
+
type: fix
|
|
7
|
+
prLink: https://github.com/FerrLabs/FerrFlow/pull/974
|
|
8
|
+
docsLink: https://ferrflow.com/docs/configuration/monorepo/
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
Path prefixes decide which package a commit belongs to. That is what the documentation says, and it is how FerrFlow decided whether a package had anything to release. It was not how FerrFlow decided what that release contained.
|
|
12
|
+
|
|
13
|
+
Each package took every commit since its own last tag. A repository with a site and a server would publish the site with the server's refactors listed underneath it, because those commits sat in the window even though nothing in them touched the site.
|
|
14
|
+
|
|
15
|
+
`ferrflow diff` was fixed to scope its range by path back in August, on the understanding that a release already worked that way. It did not, so from that point until now the preview and the release disagreed with each other, and the preview was the one telling the truth. They agree again.
|
|
16
|
+
|
|
17
|
+
The visible half is a changelog claiming work that shipped elsewhere. The half worth knowing about is the version. The bump is the strongest change in that list, so a `feat` anywhere in the repository turned every package released alongside it into a minor. A one-line fix to a site could go out as `1.1.0` because a server gained an endpoint the same week.
|
|
18
|
+
|
|
19
|
+
Releases now carry only the commits that touch the package, matching `path` and any `sharedPaths` it declares. Nothing to configure, and `sharedPaths` behaves as before: a commit under a shared directory belongs to every package that declares it, and to no other.
|
|
20
|
+
|
|
21
|
+
Expect quieter changelogs and, in mixed repositories, smaller version bumps than you have been getting. The bumps you were getting were wrong, so this is worth a look if you have release automation keyed to major or minor.
|
|
22
|
+
|
|
23
|
+
The effect is largest with `recoverMissedReleases` enabled, since recovery reaches back to the last tag rather than the last release, and everything the other packages did in between came along.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 'FerrFlow: a dependent now takes the strongest bump reaching it'
|
|
3
|
+
summary: 'A package fed by two dependency edges of different strength took whichever arrived first, so it could ship as a patch while a package it depends on moved a minor. Expect larger bumps if your graph has a diamond in it.'
|
|
4
|
+
date: 2026-09-01T18:00:00Z
|
|
5
|
+
product: ferrflow
|
|
6
|
+
type: fix
|
|
7
|
+
prLink: https://github.com/FerrLabs/FerrFlow/pull/988
|
|
8
|
+
docsLink: https://ferrflow.com/docs/configuration/monorepo/
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
When a release bumps a package, FerrFlow walks the dependency graph and bumps what depends on it. Each edge decides how much of the bump it passes on, through `propagate`.
|
|
12
|
+
|
|
13
|
+
A package sitting at the end of two edges of different strength took whichever reached it first, not the strongest. Say `web` depends on `shared` with `propagate: patch` and on `api` with the default. A feature on `shared` gives `api` a minor, and `web` should follow with a minor through that edge. It shipped as a patch instead, because the capped edge from `shared` is the shorter path and got there first:
|
|
14
|
+
|
|
15
|
+
```
|
|
16
|
+
web 1.0.0 → 1.0.1 (patch, dependency: shared, api)
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
The line already named both edges, which is what makes it awkward: FerrFlow knew about the minor and did not use it. Within a single step it always took the strongest of the edges available. The rule only broke down across steps.
|
|
20
|
+
|
|
21
|
+
It now settles: the walk repeats until no package can be improved, so the same release produces `web 1.0.0 → 1.1.0`.
|
|
22
|
+
|
|
23
|
+
**Some releases get larger.** If your graph has a diamond, a package fed by a strong and a weak path will now take the strong one, where before it depended on which path was shorter. Worth a look before upgrading if you have automation keyed to major or minor. Repositories with a straight dependency chain and no diamonds are unaffected, since there was never a second bump competing.
|
|
24
|
+
|
|
25
|
+
`ferrflow graph --impact` follows the same rule, so you can see what a release would now do before running one.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 'FerrFlow: a changelog your hook rewrote is now what gets published'
|
|
3
|
+
summary: 'A `postBump` hook could already rewrite CHANGELOG.md and have it committed, but the tag, the release body and the release commit kept the text generated before the hook ran. They now agree.'
|
|
4
|
+
date: 2026-09-01T16:00:00Z
|
|
5
|
+
product: ferrflow
|
|
6
|
+
type: fix
|
|
7
|
+
prLink: https://github.com/FerrLabs/FerrFlow/pull/982
|
|
8
|
+
docsLink: https://ferrflow.com/docs/configuration/config-file/
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
`post_bump` runs after the changelog section is written and receives it in `FERRFLOW_CHANGELOG`. A hook can rewrite `CHANGELOG.md`, and FerrFlow stages the result into the release commit. That much already worked.
|
|
12
|
+
|
|
13
|
+
What did not is everything else that quotes the changelog. The section is built before the hook runs, and that earlier value fed the git tag, the forge release body and the release commit message. So a hook that turned commit subjects into prose gave you a file that read well and a Releases page that still said `feat(auth): support passkeys`. Same release, two texts, and the one people actually read was the raw one.
|
|
14
|
+
|
|
15
|
+
FerrFlow now reads the section back from the file after the hook, so all four carry the same thing.
|
|
16
|
+
|
|
17
|
+
If a rewrite loses the `## [version]` heading, the generated text is published instead. A hook that mangles the changelog should not also empty the release notes.
|
|
18
|
+
|
|
19
|
+
This closes the gap for anyone wanting human-written release notes without FerrFlow taking a position on how they are produced. Whether the hook calls a model, runs a script, or reformats with `sed` is not FerrFlow's business, and keeping it that way means no API key passes through the release tool, nothing breaks in air-gapped CI, and the result stays reproducible if your rewriter is.
|
|
20
|
+
|
|
21
|
+
One thing to know: none of this runs under `--dry-run`, which writes no changelog. Preview it with a real release on a branch.
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 'FerrFlow: doctor now catches a lockfile that disagrees with its manifest'
|
|
3
|
+
summary: 'A package whose manifest and lockfile record different versions cannot build with `--locked`, and `ferrflow doctor` used to report it as healthy. It now says so, and warns before the drift happens.'
|
|
4
|
+
date: 2026-09-01T14:00:00Z
|
|
5
|
+
product: ferrflow
|
|
6
|
+
type: new
|
|
7
|
+
prLink: https://github.com/FerrLabs/FerrFlow/pull/981
|
|
8
|
+
docsLink: https://ferrflow.com/docs/reference/cli/
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
A release bumps the version in your manifest. If the lockfile beside it is not bumped too, cargo stops building:
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
error: cannot update the lock file because --locked was passed to prevent this
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
`doctor` had nothing to say about this. It read the manifest, printed the version it found, and moved on. A repository could sit in that state for days with a green-looking report while every `--locked` build failed.
|
|
18
|
+
|
|
19
|
+
It now reports the disagreement:
|
|
20
|
+
|
|
21
|
+
```
|
|
22
|
+
✓ api: v2026.8.1
|
|
23
|
+
⚠ api lockfile: api/Cargo.lock records v6.1.0 while api/Cargo.toml says v2026.8.1; builds passing --locked will refuse to run
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
The second check is the one worth acting on, because it fires before anything breaks. `updateLockfiles` is off by default, and a repository with a lockfile sitting next to a managed manifest and the flag unset is not broken yet, it is simply waiting for the next release to break it:
|
|
27
|
+
|
|
28
|
+
```
|
|
29
|
+
⚠ api lockfile: api/Cargo.lock is not updated on release; set updateLockfiles so the next bump does not leave it behind
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
With the flag on and the versions agreeing you get a plain `✓`, and a package with no lockfile is not mentioned.
|
|
33
|
+
|
|
34
|
+
Version comparison applies to `Cargo.lock`. pnpm, yarn, poetry, uv, bundler and mix lock dependencies without restating the version of the package that owns them, so a mismatch of this shape cannot occur there and there is nothing to compare. Those still get the `updateLockfiles` warning, which is about the setting rather than the file.
|
|
35
|
+
|
|
36
|
+
Nothing to change on your side. `doctor` stays read-only and runs no package manager, so it works on a machine with no toolchain installed and no registry access.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 'FerrFlow: see what a release drags along before you run it'
|
|
3
|
+
summary: 'In a monorepo, releasing a widely depended-on package pulls others out with it. `ferrflow graph --impact` names them, with the version each would get, before anything is tagged.'
|
|
4
|
+
date: 2026-09-01T10:00:00Z
|
|
5
|
+
product: ferrflow
|
|
6
|
+
type: new
|
|
7
|
+
prLink: https://github.com/FerrLabs/FerrFlow/pull/979
|
|
8
|
+
docsLink: https://ferrflow.com/docs/reference/cli/
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
Releasing a package that others depend on releases those too. FerrFlow has always done this, and `ferrflow graph` has always printed the topology it works from, but the two never met: you could read the graph and work out the consequences yourself, or run the release and find out.
|
|
12
|
+
|
|
13
|
+
`--impact` answers it directly:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
ferrflow graph --impact shared
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
shared 1.0.0 → 1.1.0 (minor, assumed)
|
|
21
|
+
|
|
22
|
+
would also release
|
|
23
|
+
api 1.0.0 → 1.1.0 minor bump, depends on shared
|
|
24
|
+
web 1.0.0 → 1.0.1 patch bump, depends on shared
|
|
25
|
+
mobile 1.0.0 → 1.1.0 minor bump, through api (2 deep)
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
The bump is assumed rather than read from your commits, which is the point: the useful question is usually hypothetical. `--bump major` shows what a breaking change would cost before you write it.
|
|
29
|
+
|
|
30
|
+
Three things it accounts for that are easy to get wrong on a whiteboard. A `dependsOn` entry can set `propagate` to `none`, which keeps that dependent out entirely, or to `patch`, which caps what the edge passes on, so `web` above takes a patch from the same upstream that gives `api` a minor. Members of a `linked` or `fixed` group come along with no dependency edge between them at all, which is the one most often forgotten. And transitive dependents carry their distance, so `mobile` reads as reached through `api` rather than directly.
|
|
31
|
+
|
|
32
|
+
A preview is only worth having if it matches what happens, so this shares its propagation with the release rather than reimplementing it. The rule the cascade applies each round was extracted and both call it, which means the two cannot drift apart as the logic changes.
|
|
33
|
+
|
|
34
|
+
`--json` works here as it does for the graph, if you want to gate a workflow on the answer rather than read it.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 'FerrFlow: your own commits set the floor for a bump, not the answer'
|
|
3
|
+
summary: 'A package with a fix of its own shipped as a patch even when a dependency in the same release took a minor. It now takes the stronger of the two. Expect larger bumps where a shared package and its consumers are released together.'
|
|
4
|
+
date: 2026-09-01T20:00:00Z
|
|
5
|
+
product: ferrflow
|
|
6
|
+
type: fix
|
|
7
|
+
prLink: https://github.com/FerrLabs/FerrFlow/pull/991
|
|
8
|
+
docsLink: https://ferrflow.com/docs/configuration/monorepo/
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
An earlier fix today made a package take the strongest bump reaching it through the dependency graph. That covered packages with nothing of their own to release. A package that had its own commits kept whatever those commits implied, however far its dependencies moved.
|
|
12
|
+
|
|
13
|
+
So a `fix` in `web`, released alongside an `api` that took a minor, shipped as a patch:
|
|
14
|
+
|
|
15
|
+
```
|
|
16
|
+
● shared 1.0.0 → 1.1.0 (minor)
|
|
17
|
+
● api 1.0.0 → 1.1.0 (minor, dependency: shared)
|
|
18
|
+
● web 1.0.0 → 1.0.1 (patch)
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
`web` depends on `api`. Under the default `propagate: same`, a minor in `api` is a minor for `web`, and the fix of its own does not make that smaller. Its commits set the floor. The same release now produces `web 1.0.0 → 1.1.0`.
|
|
22
|
+
|
|
23
|
+
The changelog is unchanged in content: `web` still lists its own commit, because that is still what it did. Only the version moved further.
|
|
24
|
+
|
|
25
|
+
**This reaches more releases than the earlier fix.** That one only touched packages with no commits of their own. This one applies to any package that has commits and a dependency moving in the same release, which in most monorepos is the common case rather than the edge one. If you release a shared library and its consumers together, expect the consumers to move up. Set `propagate` on the dependency to `patch` or `none` where that is not what you want.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 'FerrFlow: Ansible Galaxy collections get a version file format'
|
|
3
|
+
summary: '`galaxy.yml` carries a top-level `version:` like `Chart.yaml` and `pubspec.yaml` do, but versioning one meant falling back to the plain-text format and a hand-written regex. It is a first-class format now.'
|
|
4
|
+
date: 2026-09-02T22:00:00Z
|
|
5
|
+
product: ferrflow
|
|
6
|
+
type: new
|
|
7
|
+
prLink: https://github.com/FerrLabs/FerrFlow/pull/999
|
|
8
|
+
docsLink: https://ferrflow.com/docs/configuration/formats/
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
An Ansible collection declares its version in `galaxy.yml`, the same way a Helm chart declares it in `Chart.yaml`. FerrFlow handled the second and not the first, so a collection had to use the `txt` format and a regex written by hand, which works until someone reformats the file.
|
|
12
|
+
|
|
13
|
+
`galaxyyml` reads and writes that key directly:
|
|
14
|
+
|
|
15
|
+
```json
|
|
16
|
+
{ "path": "galaxy.yml", "format": "galaxyyml" }
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
`galaxy.yml` is also detected on its own now, so a repository with nothing but a collection manifest gets a working config without naming the format at all.
|
|
20
|
+
|
|
21
|
+
Everything around the version is left alone. The write replaces the version and nothing else, so `namespace`, `name`, `readme` and any comments come out byte-identical. A `version:` nested under another key, the way a dependency constraint is, is not touched.
|
|
22
|
+
|
|
23
|
+
Ansible was the one ecosystem gap in a list that already covered Rust, Python, Node, PHP, Java, .NET, Kubernetes, Dart, Elixir, Ruby, Swift, Haskell, C and Go.
|
|
24
|
+
|
|
25
|
+
Publishing is still yours to run. This versions the manifest; it does not call `ansible-galaxy collection publish`.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 'FerrFlow: the documentation is now open to pull requests'
|
|
3
|
+
summary: 'The pages behind ferrflow.com/docs live in the public FerrFlow repository. A wrong flag name, a stale example or a paragraph that never quite landed can now be fixed by anyone, and the fix goes live when it merges.'
|
|
4
|
+
date: 2026-09-03T09:00:00Z
|
|
5
|
+
product: ferrflow
|
|
6
|
+
type: new
|
|
7
|
+
prLink: https://github.com/FerrLabs/FerrFlow-Cloud/pull/908
|
|
8
|
+
docsLink: https://github.com/FerrLabs/FerrFlow/tree/main/docs/site
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
The FerrFlow CLI has been open source since the start, but its documentation was not. The pages lived in the private repo that builds ferrflow.com, so spotting a mistake in them and being able to fix it were two very different things.
|
|
12
|
+
|
|
13
|
+
They now live in [`docs/site`](https://github.com/FerrLabs/FerrFlow/tree/main/docs/site) of the public FerrFlow repository, next to the code they describe. Every page served under `/docs`, current and frozen, is in there.
|
|
14
|
+
|
|
15
|
+
To fix something, open a pull request against that repo. The pages ship in the `@ferrflow/doc` package and the site picks them up at build time, so there is nothing to do once the change is released.
|
|
16
|
+
|
|
17
|
+
The frozen per-version snapshots came along too, and they stay frozen. `docs/site/docs-v5/` records what FerrFlow v5 actually documented, mistakes included, because anyone still pinned to v5 reads those pages to understand the binary they are running. CI rejects a pull request that edits one and points you at the current docs instead.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 'buildMetadata: derive part of the version from your code'
|
|
3
|
+
summary: 'A new workspace field naming a command whose output is appended to the version after a plus. The suffix lands on the version files and stops there, so the tag and the changelog keep the plain version.'
|
|
4
|
+
date: 2026-09-04T20:00:00Z
|
|
5
|
+
product: ferrflow
|
|
6
|
+
type: new
|
|
7
|
+
draft: true
|
|
8
|
+
prLink: https://github.com/FerrLabs/FerrFlow/pull/1022
|
|
9
|
+
docsLink: https://ferrflow.com/docs/configuration/config-file/
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
Some versions carry a fact the commits do not know. A Minecraft server advertises the protocol range it speaks, a fork records the upstream revision it was cut from, a firmware build stamps the toolchain that produced it. Semver has a slot for exactly this, the `+suffix` at the end, and until now FerrFlow had no way to fill it: the suffix had to be reattached by a `postBump` hook that reopened the manifest FerrFlow had just written.
|
|
13
|
+
|
|
14
|
+
`workspace.buildMetadata` names a command instead. FerrFlow runs it once per release from the repository root, before writing anything, and appends its trimmed stdout to the version.
|
|
15
|
+
|
|
16
|
+
```toml
|
|
17
|
+
[workspace]
|
|
18
|
+
buildMetadata = "sh scripts/protocol-versions.sh"
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
If the script prints `26.2-26.45`, the manifest reads `1.4.0+26.2-26.45`.
|
|
22
|
+
|
|
23
|
+
**The suffix goes on the version files and nowhere else.** The tag is `v1.4.0`, the changelog heading is `1.4.0`, and the minor after it is computed from `1.4.0`. That is not a shortcut, it is what semver says: build metadata is excluded from a version's identity and ignored when comparing precedence, so `1.4.0+a` and `1.4.0+b` are the same release. A version that has already been stamped round-trips correctly, so `1.4.0+26.2-26.45` bumps to `1.5.0` and gets stamped afresh.
|
|
24
|
+
|
|
25
|
+
The output has to be dot-separated alphanumerics and hyphens, which is the full grammar semver allows after the `+`. A command that fails, prints nothing, or prints anything outside that set aborts the release rather than writing a manifest no parser will accept. Under `--dry-run` the command is printed and not executed, in line with how hooks behave.
|
|
26
|
+
|
|
27
|
+
Reach for it when the derivation is a shell one-liner or a script you already have. If you were doing this with a `postBump` hook, the hook can now shrink to the part that computes the value.
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 'FerrFlow: a schema for per-package config files'
|
|
3
|
+
summary: 'Files pulled in through include now have their own JSON schema, so editors autocomplete and validate them like the root config. It is served at ferrflow.com/schema/ferrflow-package.json and bundled in the binary behind ferrflow schema --package.'
|
|
4
|
+
date: 2026-09-22T08:07:34Z
|
|
5
|
+
product: ferrflow
|
|
6
|
+
type: new
|
|
7
|
+
prLink: https://github.com/FerrLabs/FerrFlow/pull/1127
|
|
8
|
+
docsLink: https://ferrflow.com/docs/reference/cli/
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
The `include` key lets a monorepo keep one config file per package, but those files had no schema. Pointing their `$schema` at `ferrflow.json` did not help: that schema describes the root config, with `workspace`, `include` and a `package` array, so an editor flagged every key of a single package as unexpected and offered no completion at all.
|
|
12
|
+
|
|
13
|
+
Since FerrFlow 7.23.0 an included file has a schema of its own:
|
|
14
|
+
|
|
15
|
+
```json
|
|
16
|
+
{
|
|
17
|
+
"$schema": "https://ferrflow.com/schema/ferrflow-package.json",
|
|
18
|
+
"name": "api",
|
|
19
|
+
"dependsOn": ["core"]
|
|
20
|
+
}
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
It accepts exactly the keys of a `package` entry, with `name` required and `path` optional, since `path` defaults to the file's directory. Anything else is rejected, so a misspelled key shows up in the editor before FerrFlow ever runs. The two schemas are checked against each other in FerrFlow's test suite, so the package schema cannot fall behind when a new package field lands.
|
|
24
|
+
|
|
25
|
+
For repos that would rather not fetch it, the same schema ships inside the binary:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
ferrflow schema --package --pretty --output ferrflow-package.schema.json
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Then point `$schema` at the local file.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 'FerrFlow: GITHUB_TOKEN only reaches remotes that are GitHub'
|
|
3
|
+
summary: 'A push to a remote FerrFlow could not identify used to carry GITHUB_TOKEN as its password, so a self-hosted forge or an unknown host received a GitHub credential. Each forge now pushes with its own token, and an unrecognised host gets none.'
|
|
4
|
+
date: 2026-09-22T18:36:17Z
|
|
5
|
+
product: ferrflow
|
|
6
|
+
type: security
|
|
7
|
+
prLink: https://github.com/FerrLabs/FerrFlow/pull/1152
|
|
8
|
+
docsLink: https://ferrflow.com/docs/configuration/config-file/
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
When FerrFlow pushed the release commit and tags, it picked the credential by asking one question: is this remote GitLab? Everything else got `GITHUB_TOKEN`. That covers GitHub, but also a self-hosted Gitea or Forgejo, Bitbucket, and any host whose forge could not be identified. Every GitHub Actions job has `GITHUB_TOKEN` in its environment, so a remote pointing somewhere else received a GitHub credential as its push password.
|
|
12
|
+
|
|
13
|
+
Each forge now pushes with the token it actually uses: `GITHUB_TOKEN` for GitHub, `GITLAB_TOKEN` for GitLab, `GITEA_TOKEN` or `FORGEJO_TOKEN` for Gitea and Forgejo, `BITBUCKET_TOKEN` for Bitbucket. These are the same variables the API side has always read, so the two halves can no longer disagree. `FERRFLOW_TOKEN` still works everywhere: it is the explicit "use this for whatever this remote is".
|
|
14
|
+
|
|
15
|
+
A host FerrFlow cannot identify now gets no forge token at all. If `GITHUB_TOKEN` is set and withheld, the run says so once:
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
Warning: not sending GITHUB_TOKEN to git.corp.example, which is not recognised as GitHub. Set `forge` in the config if it is a GitHub Enterprise instance, or pass the token as FERRFLOW_TOKEN.
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Two things to check if you self-host. A GitHub Enterprise instance that FerrFlow cannot reach to identify needs `"forge": "github"` under `workspace` in your config. Gitea and Forgejo Actions export their job token under the name `GITHUB_TOKEN`, so those jobs keep pushing for now, with a warning: pass it as `GITEA_TOKEN` instead, because that fallback goes away in the next major version, and creating the release already reads `GITEA_TOKEN` or `FORGEJO_TOKEN` rather than falling back.
|
|
22
|
+
|
|
23
|
+
Identifying a self-hosted host got stricter in the same pass. A GitHub Enterprise instance is recognised only by the `X-GitHub-Enterprise-Version` header its API sends, not by anything answering `/api/v3`, and the probe no longer follows redirects, so one host can no longer borrow another's answer to be handed a token. An instance in private mode, which answers 401 without a session, is now detected where it was missed before. The trade-off is that an instance which redirects its own API root is no longer detected either, and takes the same `forge` setting as above.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 'FerrFlow: releases on GitHub Actions no longer need a git identity'
|
|
3
|
+
summary: 'A release using GITHUB_TOKEN without bot mode wrote the version files and changelog, then failed on the release commit with "Author identity unknown". On Actions it now commits as github-actions[bot]; elsewhere it stops before touching anything.'
|
|
4
|
+
date: 2026-09-22T20:00:00Z
|
|
5
|
+
product: ferrflow
|
|
6
|
+
type: fix
|
|
7
|
+
draft: true
|
|
8
|
+
prLink: https://github.com/FerrLabs/FerrFlow/pull/1128
|
|
9
|
+
docsLink: https://ferrflow.com/docs/ci/github-actions/
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
Until now, FerrFlow only set a git author in bot mode. A workflow calling the action with `GITHUB_TOKEN` and no `bot: true` got as far as writing the version files and the CHANGELOG, and then `git commit` failed with `Author identity unknown`. The job left a dirty tree behind and no release.
|
|
13
|
+
|
|
14
|
+
A release now checks for an identity before it bumps anything, and it checks the same way `git commit` does. Anything git itself would accept still counts: a configured `user.name` and `user.email`, the `GIT_AUTHOR_*` variables, or an identity git works out on its own.
|
|
15
|
+
|
|
16
|
+
If there is none and the job runs on GitHub Actions, FerrFlow commits and tags as `github-actions[bot]`, the account a `GITHUB_TOKEN` push is credited to anyway. Your workflow needs no changes, and a `git config` step you already have keeps working. Anywhere else, the release stops at once with the two `git config` commands to run, and nothing is written.
|
|
17
|
+
|
|
18
|
+
`ferrflow doctor` also has a new `git identity` check, so you can catch this before a first release.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 'FerrFlow: the release pull request title now fits the forge'
|
|
3
|
+
summary: 'A monorepo releasing enough packages at once built a title longer than the 255 characters a merge request accepts, so the release PR was never opened and the run still exited green. The title is capped, the full list stays in the description, and a rejected PR now fails the release.'
|
|
4
|
+
date: 2026-09-23T09:12:00Z
|
|
5
|
+
product: ferrflow
|
|
6
|
+
type: fix
|
|
7
|
+
prLink: https://github.com/FerrLabs/FerrFlow/pull/1175
|
|
8
|
+
docsLink: https://ferrflow.com/docs/ci/pipeline-triggers/
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
In `releaseCommitMode: pr`, the pull request title is `chore(release): ` followed by every package being released. Nothing bounded it, and forges do: 255 characters on GitLab, Gitea and Forgejo, 256 on GitHub. A monorepo releasing five packages with long names crosses that line, GitLab answers 400, and the release PR is never opened.
|
|
12
|
+
|
|
13
|
+
The title is now capped at 255, the lowest of the four, so one title works on every forge. When the list does not fit, FerrFlow keeps as many packages as it can and ends the title with `and N more`. Nothing is lost: the description has always listed every tag on its own line, and still does.
|
|
14
|
+
|
|
15
|
+
The second half of this is the part you could not see. A release pull request that never got opened only produced a warning, so the branch was pushed, no PR existed, and `ferrflow release` exited 0 with CI green. That is now an error, because a PR-mode release that opened no pull request has released nothing. It covers the forge rejecting the PR, the lookup for an existing one failing, and FerrFlow not reaching a forge at all. Check that last one before you upgrade: a release job with a missing token pushed the branch and said nothing at all, and will now fail. Gitea, Forgejo and Bitbucket stay on a warning only where the forge itself refuses the pull request, since PR mode is not implemented there yet; an unreachable forge fails there too, because a missing token is caught before the forge is known.
|
|
16
|
+
|
|
17
|
+
The error also says what the forge said. FerrFlow used to drop the response body and report only `failed to created MR: E3102`, which left you guessing. It now reads:
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
Failed to create MR from ferrflow/release-main to main: http status 400: {"message":["Title is too long (maximum is 255 characters)"]}
|
|
21
|
+
```
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 'FerrFlow: a txt selector no longer eats the spaces around your version'
|
|
3
|
+
summary: 'A versioned file read through a txt selector whose capture included padding lost all of that padding on the first release, because the write replaced the whole capture. It now replaces only what the read returned.'
|
|
4
|
+
date: 2026-09-24T12:05:00Z
|
|
5
|
+
product: ferrflow
|
|
6
|
+
type: fix
|
|
7
|
+
prLink: https://github.com/FerrLabs/FerrFlow/pull/1190
|
|
8
|
+
docsLink: https://ferrflow.com/schema/ferrflow.json
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
A `txt` versioned file can name a `selector`, a regex with one capture group around the version. The write replaced the whole of that capture, so any padding the regex swallowed went with it: `version = 1.2.3` with `(?m)^version =(.+)$` came back as `version =2.0.0`.
|
|
12
|
+
|
|
13
|
+
It goes all at once, on the first release, and every release after that writes into a line that has already been stripped. The selector still matches a line that lost its space, so nothing ever reported it.
|
|
14
|
+
|
|
15
|
+
Both sides now work from the same trimmed range: the write replaces exactly what the read returned and leaves the rest of the line alone. If your selector captures padding, the padding stays where you put it.
|
|
16
|
+
|
|
17
|
+
Two smaller things come with it. A selector whose capture is only whitespace is now an error instead of an empty version on its way to a tag name, and a selector whose group never participates, which an optional group like `(?m)^version(?: =(.*))?$` allows, now fails with `E4702` and a link to the docs rather than a bare message.
|
|
18
|
+
|
|
19
|
+
This came out of the review of the read-side trim rather than a report, so you are unlikely to have chased it: until that trim landed, a padded capture also produced a padded version, and the version is what you would have noticed first.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 'FerrFlow: a versionTemplate starting with v no longer resets on every release'
|
|
3
|
+
summary: 'A versionTemplate whose first literal was v never read the previous version back, so every release started again from zero. v1.2.3 with a patch bump produced v0.0.1, release after release.'
|
|
4
|
+
date: 2026-09-24T16:20:00Z
|
|
5
|
+
product: ferrflow
|
|
6
|
+
type: fix
|
|
7
|
+
prLink: https://github.com/FerrLabs/FerrFlow/pull/1199
|
|
8
|
+
docsLink: https://ferrflow.com/docs/configuration/config-file/
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
To bump a version, FerrFlow reads the previous one back through the same template that produced it. That read stripped a leading `v` from the current version before matching, which is right when the template is bare and the version came from a tag, and wrong when the template carries the `v` itself: the pattern then asked for a `v` that had just been removed, and nothing matched.
|
|
12
|
+
|
|
13
|
+
With no previous version to read, every number fell back to zero. `v1.2.3` with a patch bump became `v0.0.1`, and the release after that became `v0.0.1` again. A `{seq}` reset the same way: `v2026.8.3` became `v2026.8.1`.
|
|
14
|
+
|
|
15
|
+
`v{major}.{minor}.{patch}` is the first template most people write, so if you use one and your versions never seemed to climb, this is why.
|
|
16
|
+
|
|
17
|
+
The version is now matched as written first, and only falls back to stripping the `v` when that fails. Both shapes work: a template carrying its own prefix, and a bare template reading a tag-shaped version.
|
|
18
|
+
|
|
19
|
+
Nothing to change on your side. The next release after upgrading reads your current version correctly and continues from it.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 'FerrFlow: versionTemplate now tells you about a bad literal instead of git'
|
|
3
|
+
summary: 'A versionTemplate whose literal text carried a space, a tab or a character git reserves produced a version that could not become a tag, and the run died at git tag with a message about ref names. The template is now checked where it is read.'
|
|
4
|
+
date: 2026-09-24T13:40:00Z
|
|
5
|
+
product: ferrflow
|
|
6
|
+
type: fix
|
|
7
|
+
prLink: https://github.com/FerrLabs/FerrFlow/pull/1194
|
|
8
|
+
docsLink: https://ferrflow.com/schema/ferrflow.json
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
`versionTemplate` checked that every `{variable}` was one it knows, and let the literal text between them through untouched. So a template with a stray space or tab produced a version carrying it, and that version went on to be a git tag, which cannot hold either.
|
|
12
|
+
|
|
13
|
+
The release failed, but at the end, with git's complaint about the ref name rather than ours about the template. You were told the tag was bad, which is true and useless.
|
|
14
|
+
|
|
15
|
+
The literals are now checked when the template is read, by `ferrflow check` and by the release alike. They may not carry whitespace, control characters, or the characters git reserves in a ref name (`~ ^ : ? * [ \`), and the error names the one it found:
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
versionTemplate "{major}.{minor}\t" has a control character ('\t') in a literal. The version becomes a git tag, which cannot carry it.
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Nothing that worked before stops working. A template rejected today already failed, later and less clearly. If `ferrflow check` starts complaining after this upgrade, it is telling you about a release that was going to break.
|