@ferrflow/doc 7.21.8 → 7.21.10

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 (9) hide show
  1. package/data/benchmarks.json +678 -678
  2. package/docs-en/ci/gitlab-ci.md +18 -4
  3. package/docs-en/reference/cli.md +2 -0
  4. package/docs-fr/ci/github-actions.md +4 -4
  5. package/docs-fr/ci/gitlab-ci.md +21 -7
  6. package/docs-fr/configuration/config-file.md +16 -16
  7. package/docs-fr/reference/cli.md +2 -0
  8. package/docs-fr/reference/errors.md +73 -73
  9. package/package.json +1 -1
package/docs-en/ci/gitlab-ci.md CHANGED
@@ -9,7 +9,9 @@ The official FerrFlow Docker image ships the binary and can be used directly as
9
9
 
10
10
  ```yaml title=".gitlab-ci.yml"
11
11
  release:
12
- image: ghcr.io/ferrlabs/ferrflow:latest
12
+ image:
13
+ name: ghcr.io/ferrlabs/ferrflow:latest
14
+ entrypoint: [""]
13
15
  stage: release
14
16
  script:
15
17
  - ferrflow release
@@ -20,6 +22,10 @@ release:
20
22
  when: on_success
21
23
  ```
22
24
 
25
+ The image's entrypoint is `ferrflow`, so `docker run ghcr.io/ferrlabs/ferrflow:latest check` works as is. GitLab runs a job's `script` through a shell instead, which is why every example here resets it with `entrypoint: [""]`. Without that line the job fails with `unrecognized subcommand 'sh'`.
26
+
27
+ The image ships `git`, trusts the checkout whatever user cloned it, and signs release commits as `FerrFlow <bot@ferrflow.com>`. To sign them as the person who triggered the pipeline instead, set `GIT_AUTHOR_NAME: $GITLAB_USER_NAME` and `GIT_AUTHOR_EMAIL: $GITLAB_USER_EMAIL` in the job variables.
28
+
23
29
  <aside class="ferr-aside ferr-aside--warning"><div class="ferr-aside__body"><p>Make sure your CI runner clones with full history. Add <code>GIT_DEPTH: 0</code> to the job variables to disable shallow cloning.</p>
24
30
  </div></aside>
25
31
 
@@ -27,7 +33,9 @@ release:
27
33
 
28
34
  ```yaml title=".gitlab-ci.yml"
29
35
  release:
30
- image: ghcr.io/ferrlabs/ferrflow:latest
36
+ image:
37
+ name: ghcr.io/ferrlabs/ferrflow:latest
38
+ entrypoint: [""]
31
39
  variables:
32
40
  GIT_DEPTH: 0 # full history: required for tag scanning
33
41
  GITLAB_TOKEN: $CI_JOB_TOKEN
@@ -43,7 +51,9 @@ If `CI_JOB_TOKEN` doesn't have permission to push tags, create a project deploy
43
51
 
44
52
  ```yaml title=".gitlab-ci.yml"
45
53
  release:
46
- image: ghcr.io/ferrlabs/ferrflow:latest
54
+ image:
55
+ name: ghcr.io/ferrlabs/ferrflow:latest
56
+ entrypoint: [""]
47
57
  variables:
48
58
  GIT_DEPTH: 0
49
59
  GITLAB_TOKEN: $FERRFLOW_DEPLOY_TOKEN # CI variable with write_repository access
@@ -59,7 +69,9 @@ FerrFlow can post a comment on every merge request showing what versions will be
59
69
 
60
70
  ```yaml title=".gitlab-ci.yml"
61
71
  ferrflow-preview:
62
- image: ghcr.io/ferrlabs/ferrflow:latest
72
+ image:
73
+ name: ghcr.io/ferrlabs/ferrflow:latest
74
+ entrypoint: [""]
63
75
  stage: test
64
76
  variables:
65
77
  GIT_DEPTH: 0
@@ -85,6 +97,8 @@ If no releasable changes are detected, the comment says so.
85
97
  <aside class="ferr-aside ferr-aside--note"><div class="ferr-aside__body"><p><code>CI_JOB_TOKEN</code> has permission to post MR notes by default. If your project restricts this, use a project access token with <code>api</code> scope stored as a CI variable.</p>
86
98
  </div></aside>
87
99
 
100
+ If you store that token as a **protected** variable, GitLab only exposes it to pipelines on protected branches and tags, and a merge request pipeline from an ordinary branch runs without it. FerrFlow then prints `Warning: preview comment not posted: no Gitlab token found in FERRFLOW_TOKEN or GITLAB_TOKEN` and the job still succeeds. Either unprotect the variable or use `CI_JOB_TOKEN`, which every job receives.
101
+
88
102
  ## GitLab Releases
89
103
 
90
104
  When `GITLAB_TOKEN` is set, FerrFlow creates a GitLab Release with the generated changelog as release notes, matching the behaviour of the GitHub integration.
package/docs-en/reference/cli.md CHANGED
@@ -76,6 +76,8 @@ ferrflow check [OPTIONS]
76
76
  | `--channel <NAME>` | Pre-release channel override (e.g. `beta`, `rc`, `dev`) |
77
77
  | `--comment` | Post a preview comment on the current PR/MR |
78
78
 
79
+ `--comment` needs a forge token (`FERRFLOW_TOKEN`, or the forge's own variable such as `GITHUB_TOKEN` or `GITLAB_TOKEN`). Without one it prints a warning naming the variables it read and posts nothing, but still exits 0, so a pull request from a fork, which gets no secrets, does not fail its pipeline. Outside a pull request or merge request it does nothing.
80
+
79
81
  ---
80
82
 
81
83
  ## `ferrflow publish`
package/docs-fr/ci/github-actions.md CHANGED
@@ -69,7 +69,7 @@ FerrFlow ajoute `[skip ci]` dans le message des commits de version par défaut p
69
69
 
70
70
  ## Commentaires de preview sur les PR
71
71
 
72
- FerrFlow peut poster un commentaire sur chaque pull request montrant quelles versions seront bump\u00e9es au merge. Le commentaire est mis \u00e0 jour automatiquement \u00e0 chaque push.
72
+ FerrFlow peut poster un commentaire sur chaque pull request montrant quelles versions seront bumpées au merge. Le commentaire est mis à jour automatiquement à chaque push.
73
73
 
74
74
  ```yaml title=".github/workflows/preview.yml"
75
75
  name: FerrFlow Preview
@@ -95,15 +95,15 @@ jobs:
95
95
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
96
96
  ```
97
97
 
98
- Si aucun changement publiable n'est d\u00e9tect\u00e9, le commentaire l'indique.
98
+ Si aucun changement publiable n'est détecté, le commentaire l'indique.
99
99
 
100
100
  ## Exemple monorepo
101
101
 
102
- Dans un monorepo, FerrFlow publie chaque package modifi\u00e9 en une seule ex\u00e9cution :
102
+ Dans un monorepo, FerrFlow publie chaque package modifié en une seule exécution :
103
103
 
104
104
  ```yaml
105
105
  - uses: FerrLabs/ferrflow@v5
106
106
  env:
107
107
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
108
- # Cr\u00e9e api@v1.3.0 et site@v0.5.1 en une seule \u00e9tape si les deux ont chang\u00e9
108
+ # Crée api@v1.3.0 et site@v0.5.1 en une seule étape si les deux ont changé
109
109
  ```
package/docs-fr/ci/gitlab-ci.md CHANGED
@@ -9,7 +9,9 @@ L'image Docker officielle FerrFlow embarque le binaire et peut être utilisée d
9
9
 
10
10
  ```yaml
11
11
  release:
12
- image: ghcr.io/ferrlabs/ferrflow:latest
12
+ image:
13
+ name: ghcr.io/ferrlabs/ferrflow:latest
14
+ entrypoint: [""]
13
15
  stage: release
14
16
  script:
15
17
  - ferrflow release
@@ -20,6 +22,10 @@ release:
20
22
  when: on_success
21
23
  ```
22
24
 
25
+ Le point d'entrée de l'image est `ferrflow`, donc `docker run ghcr.io/ferrlabs/ferrflow:latest check` fonctionne tel quel. GitLab, lui, exécute le `script` d'un job dans un shell : c'est pourquoi chaque exemple ici le réinitialise avec `entrypoint: [""]`. Sans cette ligne, le job échoue avec `unrecognized subcommand 'sh'`.
26
+
27
+ L'image embarque `git`, fait confiance au dépôt quel que soit l'utilisateur qui l'a cloné, et signe les commits de release `FerrFlow <bot@ferrflow.com>`. Pour les signer au nom de la personne qui a déclenché le pipeline, définissez `GIT_AUTHOR_NAME: $GITLAB_USER_NAME` et `GIT_AUTHOR_EMAIL: $GITLAB_USER_EMAIL` dans les variables du job.
28
+
23
29
  <aside class="ferr-aside ferr-aside--warning"><div class="ferr-aside__body"><p>Assurez-vous que votre runner CI clone avec l&#39;historique complet. Ajoutez <code>GIT_DEPTH: 0</code> aux variables du job pour désactiver le clonage superficiel.</p>
24
30
  </div></aside>
25
31
 
@@ -27,7 +33,9 @@ release:
27
33
 
28
34
  ```yaml
29
35
  release:
30
- image: ghcr.io/ferrlabs/ferrflow:latest
36
+ image:
37
+ name: ghcr.io/ferrlabs/ferrflow:latest
38
+ entrypoint: [""]
31
39
  variables:
32
40
  GIT_DEPTH: 0 # historique complet : requis pour le scan des tags
33
41
  GITLAB_TOKEN: $CI_JOB_TOKEN
@@ -43,7 +51,9 @@ Si `CI_JOB_TOKEN` n'a pas les permissions pour pousser des tags, créez un deplo
43
51
 
44
52
  ```yaml
45
53
  release:
46
- image: ghcr.io/ferrlabs/ferrflow:latest
54
+ image:
55
+ name: ghcr.io/ferrlabs/ferrflow:latest
56
+ entrypoint: [""]
47
57
  variables:
48
58
  GIT_DEPTH: 0
49
59
  GITLAB_TOKEN: $FERRFLOW_DEPLOY_TOKEN # variable CI avec accès write_repository
@@ -55,11 +65,13 @@ release:
55
65
 
56
66
  ## Commentaires de preview sur les MR
57
67
 
58
- FerrFlow peut poster un commentaire sur chaque merge request montrant quelles versions seront bump\u00e9es au merge. Le commentaire est mis \u00e0 jour automatiquement \u00e0 chaque push.
68
+ FerrFlow peut poster un commentaire sur chaque merge request montrant quelles versions seront bumpées au merge. Le commentaire est mis à jour automatiquement à chaque push.
59
69
 
60
70
  ```yaml title=".gitlab-ci.yml"
61
71
  ferrflow-preview:
62
- image: ghcr.io/ferrlabs/ferrflow:latest
72
+ image:
73
+ name: ghcr.io/ferrlabs/ferrflow:latest
74
+ entrypoint: [""]
63
75
  stage: test
64
76
  variables:
65
77
  GIT_DEPTH: 0
@@ -70,8 +82,10 @@ ferrflow-preview:
70
82
  - if: $CI_PIPELINE_SOURCE == "merge_request_event"
71
83
  ```
72
84
 
73
- Si aucun changement publiable n'est d\u00e9tect\u00e9, le commentaire l'indique.
85
+ Si aucun changement publiable n'est détecté, le commentaire l'indique.
86
+
87
+ Si vous stockez ce token dans une variable **protégée**, GitLab ne l'expose qu'aux pipelines des branches et tags protégés, et le pipeline d'une merge request venant d'une branche ordinaire tourne sans lui. FerrFlow affiche alors `Warning: preview comment not posted: no Gitlab token found in FERRFLOW_TOKEN or GITLAB_TOKEN` et le job réussit quand même. Retirez la protection de la variable, ou utilisez `CI_JOB_TOKEN`, que chaque job reçoit.
74
88
 
75
89
  ## GitLab Releases
76
90
 
77
- Lorsque `GITLAB_TOKEN` est d\u00e9fini, FerrFlow cr\u00e9e une GitLab Release avec le changelog g\u00e9n\u00e9r\u00e9 comme notes de release, de la m\u00eame mani\u00e8re que l'int\u00e9gration GitHub.
91
+ Lorsque `GITLAB_TOKEN` est défini, FerrFlow crée une GitLab Release avec le changelog généré comme notes de release, de la même manière que l'intégration GitHub.
package/docs-fr/configuration/config-file.md CHANGED
@@ -3,16 +3,16 @@ title: Configuration
3
3
  description: Référence complète du fichier de configuration FerrFlow.
4
4
  ---
5
5
 
6
- FerrFlow supporte six formats de fichier de configuration, recherch\u00e9s dans cet ordre :
6
+ FerrFlow supporte six formats de fichier de configuration, recherchés dans cet ordre :
7
7
 
8
8
  1. `ferrflow.json`
9
9
  2. `ferrflow.json5`
10
10
  3. `ferrflow.toml`
11
- 4. `ferrflow.ts` (n\u00e9cessite `tsx`)
12
- 5. `ferrflow.js` (n\u00e9cessite `node`)
11
+ 4. `ferrflow.ts` (nécessite `tsx`)
12
+ 5. `ferrflow.js` (nécessite `node`)
13
13
  6. `.ferrflow` (JSON)
14
14
 
15
- Si aucun fichier de configuration n'est trouv\u00e9, FerrFlow d\u00e9tecte automatiquement les fichiers de version courants dans le r\u00e9pertoire actuel.
15
+ Si aucun fichier de configuration n'est trouvé, FerrFlow détecte automatiquement les fichiers de version courants dans le répertoire actuel.
16
16
 
17
17
  <aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Ajoutez <code>&quot;$schema&quot;: &quot;https://ferrflow.com/schema/ferrflow.json&quot;</code> à votre configuration JSON pour l&#39;autocomplétion et la validation dans votre éditeur.</p>
18
18
  </div></aside>
@@ -88,19 +88,19 @@ format = &quot;toml&quot;
88
88
  </div></div>
89
89
  </div>
90
90
 
91
- <aside class="ferr-aside ferr-aside--note"><div class="ferr-aside__body"><p>Les configurations JSON, JSON5, et TypeScript/JavaScript utilisent des cl\u00e9s en <strong>camelCase</strong> (<code>tagTemplate</code>, <code>versionedFiles</code>).
92
- La configuration TOML utilise des cl\u00e9s en <strong>snake_case</strong> (<code>tag_template</code>, <code>versioned_files</code>).
93
- Toutes les formes sont \u00e9quivalentes.</p>
91
+ <aside class="ferr-aside ferr-aside--note"><div class="ferr-aside__body"><p>Les configurations JSON, JSON5, et TypeScript/JavaScript utilisent des clés en <strong>camelCase</strong> (<code>tagTemplate</code>, <code>versionedFiles</code>).
92
+ La configuration TOML utilise des clés en <strong>snake_case</strong> (<code>tag_template</code>, <code>versioned_files</code>).
93
+ Toutes les formes sont équivalentes.</p>
94
94
  </div></aside>
95
95
 
96
96
  ### Configurations TypeScript et JavaScript
97
97
 
98
- Les fichiers de config TypeScript (`.ts`) et JavaScript (`.js`) utilisent un export ESM par d\u00e9faut. L'export peut \u00eatre un objet ou une fonction asynchrone.
98
+ Les fichiers de config TypeScript (`.ts`) et JavaScript (`.js`) utilisent un export ESM par défaut. L'export peut être un objet ou une fonction asynchrone.
99
99
 
100
- <aside class="ferr-aside ferr-aside--warning"><div class="ferr-aside__body"><p>Les configs TypeScript n\u00e9cessitent <code>tsx</code> (<code>npm install -g tsx</code>). Les configs JavaScript n\u00e9cessitent <code>node</code> (v18+).</p>
100
+ <aside class="ferr-aside ferr-aside--warning"><div class="ferr-aside__body"><p>Les configs TypeScript nécessitent <code>tsx</code> (<code>npm install -g tsx</code>). Les configs JavaScript nécessitent <code>node</code> (v18+).</p>
101
101
  </div></aside>
102
102
 
103
- L'avantage principal des configs TS/JS : les **hooks sous forme de fonctions**. Au lieu de commandes shell, vous pouvez \u00e9crire des hooks natifs avec acc\u00e8s complet au contexte :
103
+ L'avantage principal des configs TS/JS : les **hooks sous forme de fonctions**. Au lieu de commandes shell, vous pouvez écrire des hooks natifs avec accès complet au contexte :
104
104
 
105
105
  ```ts title="ferrflow.ts"
106
106
  export default {
@@ -129,19 +129,19 @@ export default {
129
129
 
130
130
  #### Objet de contexte des hooks
131
131
 
132
- Les hooks en fonction re\u00e7oivent un objet de contexte avec ces champs :
132
+ Les hooks en fonction reçoivent un objet de contexte avec ces champs :
133
133
 
134
134
  | Champ | Type | Description |
135
135
  | -------------- | -------------- | ---------------------------------------------------------------------------- |
136
136
  | `package` | string | Nom du package |
137
- | `oldVersion` | string | Version avant le bump (vide pour la premi\u00e8re release) |
138
- | `newVersion` | string | Version apr\u00e8s le bump |
137
+ | `oldVersion` | string | Version avant le bump (vide pour la première release) |
138
+ | `newVersion` | string | Version après le bump |
139
139
  | `bumpType` | string | `major`, `minor`, `patch`, ou `none` |
140
140
  | `tag` | string | Nom complet du tag git |
141
141
  | `dryRun` | boolean | Vrai si `--dry-run` est actif |
142
142
  | `packagePath` | string | Chemin absolu vers la racine du package |
143
- | `channel` | string ou null | Nom du channel de pr\u00e9-release |
144
- | `isPrerelease` | boolean | Vrai si c'est une pr\u00e9-release |
143
+ | `channel` | string ou null | Nom du channel de pré-release |
144
+ | `isPrerelease` | boolean | Vrai si c'est une pré-release |
145
145
  | `monorepo` | boolean | Vrai si c'est une release monorepo |
146
146
  | `changelog` | string | Section de changelog rendue pour ce bump (markdown) |
147
147
  | `commits` | array | `{ hash, message, type?, scope?, breaking }` par commit du bump |
@@ -165,7 +165,7 @@ export default {
165
165
  };
166
166
  ```
167
167
 
168
- Les hooks sous forme de commandes shell et de fonctions peuvent \u00eatre m\u00e9lang\u00e9s dans la m\u00eame config.
168
+ Les hooks sous forme de commandes shell et de fonctions peuvent être mélangés dans la même config.
169
169
 
170
170
  ## `workspace`
171
171
 
package/docs-fr/reference/cli.md CHANGED
@@ -45,6 +45,8 @@ ferrflow check [OPTIONS]
45
45
  | `--channel <NAME>` | Canal de pré-release à utiliser (ex. `beta`, `rc`, `dev`) |
46
46
  | `--comment` | Poster un commentaire de prévisualisation sur la PR/MR courante |
47
47
 
48
+ `--comment` a besoin d'un token de forge (`FERRFLOW_TOKEN`, ou la variable propre à la forge comme `GITHUB_TOKEN` ou `GITLAB_TOKEN`). Sans token, la commande affiche un avertissement qui nomme les variables lues et ne poste rien, mais sort quand même avec le code 0, pour qu'une pull request venant d'un fork, qui ne reçoit aucun secret, ne fasse pas échouer son pipeline. Hors d'une pull request ou d'une merge request, elle ne fait rien.
49
+
48
50
  ---
49
51
 
50
52
  ## `ferrflow publish`