@ferrflow/doc 7.36.5 → 7.36.7
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-11-15-ferrflow-monorepo-github-latest.md +12 -0
- package/data/benchmarks.json +714 -714
- package/docs-en/configuration/config-file.md +1 -1
- package/docs-en/configuration/monorepo.md +17 -0
- package/docs-en/reference/api.md +12 -14
- package/docs-fr/configuration/config-file.md +1 -1
- package/docs-fr/configuration/monorepo.md +17 -0
- package/docs-fr/reference/api.md +12 -14
- package/package.json +1 -1
|
@@ -201,7 +201,7 @@ Global settings that apply to all packages.
|
|
|
201
201
|
| `updateDependents` | boolean | `false` | After a bump, rewrite the version constraint every dependent declares for the bumped package and stage the manifest in the same release commit. Only `json` (`dependencies`, `devDependencies`, `peerDependencies`, `optionalDependencies`) and `toml` (`dependencies`, `dev-dependencies`, `build-dependencies`) manifests are rewritten, and only plain operator + version constraints — the operator is preserved (`^1.2.3` → `^2.0.0`). A `workspace:*`, `file:`/`git:` spec, `1.x` or a multi-part range is left untouched. |
|
|
202
202
|
| `nestedPackages` | string | `"shared"` | When one package's path contains another's, which packages a file under the inner path counts for. `shared` counts it for both; `exclusive` gives it to the package with the longest matching path. See [Nested packages](/docs/configuration/monorepo#nested-packages). |
|
|
203
203
|
| `floatingTags` | array | `[]` | Floating tag levels to create on each release: `"major"`, `"minor"`. For example, `["major"]` creates a `v1` tag that always points to the latest `v1.x.y` release. |
|
|
204
|
-
| `latestTag` | string | none | Template for a floating alias tag that always points at the package's newest non-prerelease release, e.g. `"latest"` or `"{name}@latest"`. Absent by default. Deliberately **not** derived from `tagTemplate`: the alias is a name, not a version, so a `tagTemplate` of `v{version}` yields `latest`, never `vlatest`. In a monorepo the template must contain `{name}`, otherwise every package overwrites the same ref and the last one released wins. Prereleases never move it, and neither does a hotfix on an older line: releasing 1.2.4 after 2.0.0 leaves it on 2.0.0 unless you pass `--force`. |
|
|
204
|
+
| `latestTag` | string | none | Template for a floating alias tag that always points at the package's newest non-prerelease release, e.g. `"latest"` or `"{name}@latest"`. Absent by default. Deliberately **not** derived from `tagTemplate`: the alias is a name, not a version, so a `tagTemplate` of `v{version}` yields `latest`, never `vlatest`. In a monorepo the template must contain `{name}`, otherwise every package overwrites the same ref and the last one released wins; the one package that may leave it out is the one that owns the repo-wide alias, and it is also the only one whose GitHub release can be marked Latest (see [Latest release on GitHub](/docs/configuration/monorepo#latest-release-on-github)). Prereleases never move it, and neither does a hotfix on an older line: releasing 1.2.4 after 2.0.0 leaves it on 2.0.0 unless you pass `--force`. |
|
|
205
205
|
| `orphanedTagStrategy` | string | `"warn"` | How to handle tags pointing to orphaned commits after rebase + force-push: `"warn"`, `"treeHash"`, or `"message"` |
|
|
206
206
|
| `branches` | array | `[]` | Map branches to pre-release channels (see [Pre-release channels](#pre-release-channels)). |
|
|
207
207
|
| `linked` | array | `[]` | Groups of packages that share a version line when co-released. When any member has a releasable commit, all members bump to the same (highest) version (see [Linked and fixed version groups](/docs/configuration/monorepo#linked-and-fixed-version-groups)). |
|
|
@@ -316,6 +316,23 @@ For a single-package repo, the default is `v{version}` (no name prefix).
|
|
|
316
316
|
|
|
317
317
|
FerrFlow looks for the most recent tag matching the template to determine what commits are new.
|
|
318
318
|
|
|
319
|
+
## Latest release on GitHub
|
|
320
|
+
|
|
321
|
+
GitHub marks one release per repository as Latest, and `releases/latest/download/...` URLs resolve to it. By default the release published last takes the flag, so in a monorepo any package can end up as Latest.
|
|
322
|
+
|
|
323
|
+
When one package owns the repo-wide alias, FerrFlow keeps the flag on it. A package owns it when its `latestTag` (its own, or the inherited workspace one) is set and has no `{name}` placeholder. Every other package in the repo is created and published with `make_latest: false`, including drafts published later by `ferrflow release`.
|
|
324
|
+
|
|
325
|
+
```json
|
|
326
|
+
{
|
|
327
|
+
"package": [
|
|
328
|
+
{ "name": "cli", "path": ".", "tagTemplate": "v{version}", "latestTag": "latest" },
|
|
329
|
+
{ "name": "site", "path": "site", "tagTemplate": "{name}@v{version}", "latestTag": "{name}@latest" }
|
|
330
|
+
]
|
|
331
|
+
}
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
Here `v1.4.0` can become Latest and `site@v2026.11.1` never does. If no package owns the alias, or the repo has a single package, nothing is sent and GitHub's default applies. GitLab, Gitea and Bitbucket have no equivalent flag and are unaffected.
|
|
335
|
+
|
|
319
336
|
## Independent cadences
|
|
320
337
|
|
|
321
338
|
Packages release independently. In a single `ferrflow release` run:
|
package/docs-en/reference/api.md
CHANGED
|
@@ -3,13 +3,11 @@ title: FerrFlow API
|
|
|
3
3
|
description: 'Hosted HTTP endpoints for FerrFlow: validate configs, preview version bumps, resolve the latest release, and fetch the config schema.'
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
The FerrFlow API exposes a small set of hosted HTTP endpoints under `https://api.ferrflow.com/
|
|
6
|
+
The FerrFlow API exposes a small set of hosted HTTP endpoints under `https://api.ferrflow.com/ferrflow/*`. They are backed by the same FerrFlow core the CLI runs, so `validate` and `preview` return results identical to `ferrflow validate` and `ferrflow check`. No second implementation to drift.
|
|
7
7
|
|
|
8
|
-
Every endpoint is public (no authentication) and safe to call from CI, editors, or a browser. The machine-readable contract is served at [`/
|
|
8
|
+
Every endpoint is public (no authentication) and safe to call from CI, editors, or a browser. The machine-readable contract is served at [`/ferrflow/openapi.json`](https://api.ferrflow.com/ferrflow/openapi.json) (OpenAPI 3.1).
|
|
9
9
|
|
|
10
|
-
`
|
|
11
|
-
|
|
12
|
-
## `GET /v1/ferrflow/health`
|
|
10
|
+
## `GET /ferrflow/health`
|
|
13
11
|
|
|
14
12
|
Liveness and version probe. Powers status dashboards.
|
|
15
13
|
|
|
@@ -17,22 +15,22 @@ Liveness and version probe. Powers status dashboards.
|
|
|
17
15
|
{ "status": "ok", "service": "ferrflow-api", "version": "10.17.0", "time": "2026-07-21T15:00:00Z" }
|
|
18
16
|
```
|
|
19
17
|
|
|
20
|
-
## `GET /
|
|
18
|
+
## `GET /ferrflow/schema`
|
|
21
19
|
|
|
22
20
|
Returns the config JSON Schema (`Content-Type: application/schema+json`), served from the schema bundled in the FerrFlow release: the same bytes the CLI validates against. Sends a strong `ETag` and `Cache-Control`, so point your editor's `$schema` here:
|
|
23
21
|
|
|
24
22
|
```json
|
|
25
|
-
{ "$schema": "https://api.ferrflow.com/
|
|
23
|
+
{ "$schema": "https://api.ferrflow.com/ferrflow/schema" }
|
|
26
24
|
```
|
|
27
25
|
|
|
28
|
-
`GET /
|
|
26
|
+
`GET /ferrflow/schema/v{major}` returns the schema frozen at a CLI major (e.g. `/schema/v5`). Only the current major is served today; older majors return `404` until per-major snapshots land.
|
|
29
27
|
|
|
30
|
-
## `GET /
|
|
28
|
+
## `GET /ferrflow/latest`
|
|
31
29
|
|
|
32
30
|
Resolves the latest FerrFlow release from GitHub, cached server-side. Pass `platform` to get a single asset:
|
|
33
31
|
|
|
34
32
|
```bash
|
|
35
|
-
curl "https://api.ferrflow.com/
|
|
33
|
+
curl "https://api.ferrflow.com/ferrflow/latest?platform=linux-x64"
|
|
36
34
|
```
|
|
37
35
|
|
|
38
36
|
```json
|
|
@@ -48,12 +46,12 @@ curl "https://api.ferrflow.com/v1/ferrflow/latest?platform=linux-x64"
|
|
|
48
46
|
|
|
49
47
|
Releases are signed with [Sigstore](/docs/verifying-releases/): verify the `.bundle` rather than a checksum (releases up to v5.47.4 carry a `.sig` + `.crt` pair instead). Without `platform`, the response lists `assets` for every platform. Valid platforms: `linux-x64`, `linux-arm64`, `linux-arm`, `darwin-x64`, `darwin-arm64`, `win32-x64`, `win32-arm64`.
|
|
50
48
|
|
|
51
|
-
## `POST /
|
|
49
|
+
## `POST /ferrflow/validate`
|
|
52
50
|
|
|
53
51
|
Validates a config without a repo. You send the config text and, optionally, the contents of the versioned files it references so the file-existence and version-consistency checks run. The result is identical to `ferrflow validate --json`.
|
|
54
52
|
|
|
55
53
|
```bash
|
|
56
|
-
curl -X POST https://api.ferrflow.com/
|
|
54
|
+
curl -X POST https://api.ferrflow.com/ferrflow/validate \
|
|
57
55
|
-H 'content-type: application/json' \
|
|
58
56
|
-d '{
|
|
59
57
|
"config": "{\"package\":[{\"name\":\"app\",\"path\":\".\",\"versionedFiles\":[{\"path\":\"package.json\",\"format\":\"json\"}]}]}",
|
|
@@ -74,12 +72,12 @@ curl -X POST https://api.ferrflow.com/v1/ferrflow/validate \
|
|
|
74
72
|
|
|
75
73
|
An invalid config is still a successful validation: the response is `200` with `"valid": false` and the offending entries. Only a malformed request body returns `400`. The optional `format` field (`json` | `json5` | `toml`) skips format inference.
|
|
76
74
|
|
|
77
|
-
## `POST /
|
|
75
|
+
## `POST /ferrflow/preview`
|
|
78
76
|
|
|
79
77
|
Computes the version bumps and changelog for an explicit list of commits: the same logic as `ferrflow check`, as a service. No repo access; you pass the commits.
|
|
80
78
|
|
|
81
79
|
```bash
|
|
82
|
-
curl -X POST https://api.ferrflow.com/
|
|
80
|
+
curl -X POST https://api.ferrflow.com/ferrflow/preview \
|
|
83
81
|
-H 'content-type: application/json' \
|
|
84
82
|
-d '{
|
|
85
83
|
"config": "{\"package\":[{\"name\":\"api\",\"path\":\".\"}]}",
|
|
@@ -184,7 +184,7 @@ Paramètres globaux qui s'appliquent à tous les packages.
|
|
|
184
184
|
| `remote` | string | `"origin"` | Remote git vers lequel pousser |
|
|
185
185
|
| `branch` | string | auto-détecté | Branche vers laquelle pousser (détectée depuis le HEAD du remote) |
|
|
186
186
|
| `tagTemplate` | string | `"v{version}"` ou `"{name}@v{version}"` | Modèle de nommage des tags. Utilise les placeholders `{version}` et `{name}`. Par défaut `v{version}` pour les repos mono-package et `{name}@v{version}` pour les monorepos. |
|
|
187
|
-
| `latestTag` | string | aucun | Modèle d'un tag alias flottant qui pointe toujours vers la dernière version non-préversion du package, par exemple `"latest"` ou `"{name}@latest"`. Absent par défaut. Volontairement **non** dérivé de `tagTemplate` : l'alias est un nom, pas une version, donc un `tagTemplate` en `v{version}` donne `latest`, jamais `vlatest`. En monorepo le modèle doit contenir `{name}`, sinon chaque package écrase le même ref et le dernier publié gagne. Les préversions ne le déplacent jamais, pas plus qu'un hotfix sur une ligne plus ancienne : publier 1.2.4 après 2.0.0 le laisse sur 2.0.0, sauf avec `--force`. |
|
|
187
|
+
| `latestTag` | string | aucun | Modèle d'un tag alias flottant qui pointe toujours vers la dernière version non-préversion du package, par exemple `"latest"` ou `"{name}@latest"`. Absent par défaut. Volontairement **non** dérivé de `tagTemplate` : l'alias est un nom, pas une version, donc un `tagTemplate` en `v{version}` donne `latest`, jamais `vlatest`. En monorepo le modèle doit contenir `{name}`, sinon chaque package écrase le même ref et le dernier publié gagne ; le seul package qui peut l'omettre est celui qui possède l'alias du dépôt, et c'est aussi le seul dont la release GitHub peut être marquée Latest (voir [Release Latest sur GitHub](/docs/configuration/monorepo#release-latest-sur-github)). Les préversions ne le déplacent jamais, pas plus qu'un hotfix sur une ligne plus ancienne : publier 1.2.4 après 2.0.0 le laisse sur 2.0.0, sauf avec `--force`. |
|
|
188
188
|
| `versioning` | string | `"semver"` | Stratégie de versionnage par défaut pour tous les packages |
|
|
189
189
|
| `preMajor` | object | unset | Remappe le bump d'un projet `semver` tant que sa majeure vaut 0, voir [Règles de bump avant 1.0](#regles-de-bump-avant-10) |
|
|
190
190
|
| `releaseCommitMode` | string | `"commit"` | Gestion du commit de release : `"commit"`, `"pr"` ou `"none"` |
|
|
@@ -283,6 +283,23 @@ Pour un repo mono-package, le défaut est `v{version}` (sans préfixe de nom).
|
|
|
283
283
|
|
|
284
284
|
FerrFlow recherche le tag le plus récent correspondant au modèle pour déterminer quels commits sont nouveaux.
|
|
285
285
|
|
|
286
|
+
## Release Latest sur GitHub
|
|
287
|
+
|
|
288
|
+
GitHub marque une release par dépôt comme Latest, et les URL `releases/latest/download/...` pointent vers elle. Par défaut, la dernière release publiée prend le drapeau : en monorepo, n'importe quel package peut donc devenir Latest.
|
|
289
|
+
|
|
290
|
+
Quand un package possède l'alias du dépôt, FerrFlow lui garde le drapeau. Un package le possède quand son `latestTag` (le sien ou celui hérité du workspace) est défini et ne contient pas `{name}`. Tous les autres packages du dépôt sont créés et publiés avec `make_latest: false`, y compris les brouillons publiés ensuite par `ferrflow release`.
|
|
291
|
+
|
|
292
|
+
```json
|
|
293
|
+
{
|
|
294
|
+
"package": [
|
|
295
|
+
{ "name": "cli", "path": ".", "tagTemplate": "v{version}", "latestTag": "latest" },
|
|
296
|
+
{ "name": "site", "path": "site", "tagTemplate": "{name}@v{version}", "latestTag": "{name}@latest" }
|
|
297
|
+
]
|
|
298
|
+
}
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
Ici `v1.4.0` peut devenir Latest et `site@v2026.11.1` jamais. Si aucun package ne possède l'alias, ou si le dépôt n'a qu'un package, rien n'est envoyé et le comportement par défaut de GitHub s'applique. GitLab, Gitea et Bitbucket n'ont pas de drapeau équivalent et ne sont pas concernés.
|
|
302
|
+
|
|
286
303
|
## Cadences indépendantes
|
|
287
304
|
|
|
288
305
|
Les packages sont publiés indépendamment. Dans une seule exécution de `ferrflow release` :
|
package/docs-fr/reference/api.md
CHANGED
|
@@ -3,13 +3,11 @@ title: API FerrFlow
|
|
|
3
3
|
description: 'Endpoints HTTP hébergés pour FerrFlow : valider une config, prévisualiser les montées de version, résoudre la dernière release et récupérer le schéma de config.'
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
L'API FerrFlow expose un petit ensemble d'endpoints HTTP hébergés sous `https://api.ferrflow.com/
|
|
6
|
+
L'API FerrFlow expose un petit ensemble d'endpoints HTTP hébergés sous `https://api.ferrflow.com/ferrflow/*`. Ils s'appuient sur le même cœur FerrFlow que le CLI : `validate` et `preview` renvoient donc des résultats identiques à `ferrflow validate` et `ferrflow check` : aucune seconde implémentation qui pourrait diverger.
|
|
7
7
|
|
|
8
|
-
Chaque endpoint est public (sans authentification) et sûr à appeler depuis la CI, un éditeur ou un navigateur. Le contrat lisible par machine est servi sur [`/
|
|
8
|
+
Chaque endpoint est public (sans authentification) et sûr à appeler depuis la CI, un éditeur ou un navigateur. Le contrat lisible par machine est servi sur [`/ferrflow/openapi.json`](https://api.ferrflow.com/ferrflow/openapi.json) (OpenAPI 3.1).
|
|
9
9
|
|
|
10
|
-
`
|
|
11
|
-
|
|
12
|
-
## `GET /v1/ferrflow/health`
|
|
10
|
+
## `GET /ferrflow/health`
|
|
13
11
|
|
|
14
12
|
Sonde de disponibilité et de version. Alimente les tableaux de bord d'état.
|
|
15
13
|
|
|
@@ -17,22 +15,22 @@ Sonde de disponibilité et de version. Alimente les tableaux de bord d'état.
|
|
|
17
15
|
{ "status": "ok", "service": "ferrflow-api", "version": "10.17.0", "time": "2026-07-21T15:00:00Z" }
|
|
18
16
|
```
|
|
19
17
|
|
|
20
|
-
## `GET /
|
|
18
|
+
## `GET /ferrflow/schema`
|
|
21
19
|
|
|
22
20
|
Renvoie le schéma JSON de la config (`Content-Type: application/schema+json`), servi depuis le schéma embarqué dans la release FerrFlow. Les octets exacts que le CLI utilise pour valider. Envoie un `ETag` fort et un `Cache-Control`, alors pointez le `$schema` de votre éditeur ici :
|
|
23
21
|
|
|
24
22
|
```json
|
|
25
|
-
{ "$schema": "https://api.ferrflow.com/
|
|
23
|
+
{ "$schema": "https://api.ferrflow.com/ferrflow/schema" }
|
|
26
24
|
```
|
|
27
25
|
|
|
28
|
-
`GET /
|
|
26
|
+
`GET /ferrflow/schema/v{major}` renvoie le schéma figé à un majeur du CLI (par ex. `/schema/v5`). Seul le majeur courant est servi aujourd'hui ; les majeurs plus anciens renvoient `404` jusqu'à l'arrivée des instantanés par majeur.
|
|
29
27
|
|
|
30
|
-
## `GET /
|
|
28
|
+
## `GET /ferrflow/latest`
|
|
31
29
|
|
|
32
30
|
Résout la dernière release FerrFlow depuis GitHub, mise en cache côté serveur. Passez `platform` pour obtenir un seul artefact :
|
|
33
31
|
|
|
34
32
|
```bash
|
|
35
|
-
curl "https://api.ferrflow.com/
|
|
33
|
+
curl "https://api.ferrflow.com/ferrflow/latest?platform=linux-x64"
|
|
36
34
|
```
|
|
37
35
|
|
|
38
36
|
```json
|
|
@@ -48,12 +46,12 @@ curl "https://api.ferrflow.com/v1/ferrflow/latest?platform=linux-x64"
|
|
|
48
46
|
|
|
49
47
|
Les releases sont signées avec [Sigstore](/fr/docs/verifying-releases/) : vérifiez le `.bundle` plutôt qu'une somme de contrôle (les releases jusqu'à v5.47.4 embarquent une paire `.sig` + `.crt`). Sans `platform`, la réponse liste les `assets` de chaque plateforme. Plateformes valides : `linux-x64`, `linux-arm64`, `linux-arm`, `darwin-x64`, `darwin-arm64`, `win32-x64`, `win32-arm64`.
|
|
50
48
|
|
|
51
|
-
## `POST /
|
|
49
|
+
## `POST /ferrflow/validate`
|
|
52
50
|
|
|
53
51
|
Valide une config sans dépôt : vous envoyez le texte de la config et, en option, le contenu des fichiers versionnés qu'elle référence pour que les vérifications d'existence et de cohérence des versions s'exécutent. Le résultat est identique à `ferrflow validate --json`.
|
|
54
52
|
|
|
55
53
|
```bash
|
|
56
|
-
curl -X POST https://api.ferrflow.com/
|
|
54
|
+
curl -X POST https://api.ferrflow.com/ferrflow/validate \
|
|
57
55
|
-H 'content-type: application/json' \
|
|
58
56
|
-d '{
|
|
59
57
|
"config": "{\"package\":[{\"name\":\"app\",\"path\":\".\",\"versionedFiles\":[{\"path\":\"package.json\",\"format\":\"json\"}]}]}",
|
|
@@ -74,12 +72,12 @@ curl -X POST https://api.ferrflow.com/v1/ferrflow/validate \
|
|
|
74
72
|
|
|
75
73
|
Une config invalide reste une validation réussie : la réponse est `200` avec `"valid": false` et les entrées fautives. Seul un corps de requête malformé renvoie `400`. Le champ optionnel `format` (`json` | `json5` | `toml`) court-circuite la détection de format.
|
|
76
74
|
|
|
77
|
-
## `POST /
|
|
75
|
+
## `POST /ferrflow/preview`
|
|
78
76
|
|
|
79
77
|
Calcule les montées de version et le changelog pour une liste explicite de commits. La même logique que `ferrflow check`, sous forme de service. Aucun accès au dépôt ; vous passez les commits.
|
|
80
78
|
|
|
81
79
|
```bash
|
|
82
|
-
curl -X POST https://api.ferrflow.com/
|
|
80
|
+
curl -X POST https://api.ferrflow.com/ferrflow/preview \
|
|
83
81
|
-H 'content-type: application/json' \
|
|
84
82
|
-d '{
|
|
85
83
|
"config": "{\"package\":[{\"name\":\"api\",\"path\":\".\"}]}",
|