@ferrflow/doc 7.21.9 → 7.22.0

package/docs-en/ci/gitlab-ci.md

@@ -9,7 +9,9 @@ The official FerrFlow Docker image ships the binary and can be used directly as
 
 ```yaml title=".gitlab-ci.yml"
 release:
-  image: ghcr.io/ferrlabs/ferrflow:latest
+  image:
+    name: ghcr.io/ferrlabs/ferrflow:latest
+    entrypoint: [""]
   stage: release
   script:
     - ferrflow release
@@ -20,6 +22,10 @@ release:
       when: on_success
 ```
 
+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'`.
+
+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.
+
 <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>
 </div></aside>
 
@@ -27,7 +33,9 @@ release:
 
 ```yaml title=".gitlab-ci.yml"
 release:
-  image: ghcr.io/ferrlabs/ferrflow:latest
+  image:
+    name: ghcr.io/ferrlabs/ferrflow:latest
+    entrypoint: [""]
   variables:
     GIT_DEPTH: 0 # full history: required for tag scanning
     GITLAB_TOKEN: $CI_JOB_TOKEN
@@ -37,13 +45,21 @@ release:
     - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
 ```
 
+## Using `CI_JOB_TOKEN`
+
+The examples above pass the job token as `GITLAB_TOKEN: $CI_JOB_TOKEN`. FerrFlow recognises it because its value equals `CI_JOB_TOKEN`, and authenticates the way GitLab expects for a job token: API calls carry a `JOB-TOKEN` header and git pushes as `gitlab-ci-token`. The same applies when the job token is passed as `FERRFLOW_TOKEN`. Any other token (project, group or personal access token) is sent as `PRIVATE-TOKEN` and pushes as `oauth2`.
+
+What a job token may do is set per project under **Settings > CI/CD > Job token permissions**. Pushing the release commit and tags needs **Allow Git push requests to the repository**. When GitLab refuses one of the API calls FerrFlow makes with a job token, use a project access token with the `api` scope instead.
+
 ## Using a deploy token
 
 If `CI_JOB_TOKEN` doesn't have permission to push tags, create a project deploy token with `write_repository` access and store it as a CI variable:
 
 ```yaml title=".gitlab-ci.yml"
 release:
-  image: ghcr.io/ferrlabs/ferrflow:latest
+  image:
+    name: ghcr.io/ferrlabs/ferrflow:latest
+    entrypoint: [""]
   variables:
     GIT_DEPTH: 0
     GITLAB_TOKEN: $FERRFLOW_DEPLOY_TOKEN # CI variable with write_repository access
@@ -59,7 +75,9 @@ FerrFlow can post a comment on every merge request showing what versions will be
 
 ```yaml title=".gitlab-ci.yml"
 ferrflow-preview:
-  image: ghcr.io/ferrlabs/ferrflow:latest
+  image:
+    name: ghcr.io/ferrlabs/ferrflow:latest
+    entrypoint: [""]
   stage: test
   variables:
     GIT_DEPTH: 0

package/docs-en/configuration/config-file.md

@@ -17,6 +17,14 @@ If no config file is found, FerrFlow auto-detects common version files in the cu
 <aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Add <code>&quot;$schema&quot;: &quot;https://ferrflow.com/schema/ferrflow.json&quot;</code> to your JSON config for editor autocompletion and validation.</p>
 </div></aside>
 
+FerrFlow warns about any key it does not recognise, in every config format and in included files, and suggests the closest valid key when there is one. The key is ignored and the command carries on:
+
+```
+Warning: unknown key `workspace.hooks.post-bump` in ferrflow.json, ignored. Did you mean `postBump`?
+```
+
+A misspelled option otherwise looks exactly like one left at its default, so treat these warnings as errors in your config.
+
 ## Config formats
 
 <div class="ferr-tabs">

package/docs-fr/ci/github-actions.md

@@ -69,7 +69,7 @@ FerrFlow ajoute `[skip ci]` dans le message des commits de version par défaut p
 
 ## Commentaires de preview sur les PR
 
-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.
+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.
 
 ```yaml title=".github/workflows/preview.yml"
 name: FerrFlow Preview
@@ -95,15 +95,15 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-Si aucun changement publiable n'est d\u00e9tect\u00e9, le commentaire l'indique.
+Si aucun changement publiable n'est détecté, le commentaire l'indique.
 
 ## Exemple monorepo
 
-Dans un monorepo, FerrFlow publie chaque package modifi\u00e9 en une seule ex\u00e9cution :
+Dans un monorepo, FerrFlow publie chaque package modifié en une seule exécution :
 
 ```yaml
 - uses: FerrLabs/ferrflow@v5
   env:
     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-# Cr\u00e9e api@v1.3.0 et site@v0.5.1 en une seule \u00e9tape si les deux ont chang\u00e9
+# Crée api@v1.3.0 et site@v0.5.1 en une seule étape si les deux ont changé
 ```

package/docs-fr/ci/gitlab-ci.md

@@ -9,7 +9,9 @@ L'image Docker officielle FerrFlow embarque le binaire et peut être utilisée d
 
 ```yaml
 release:
-  image: ghcr.io/ferrlabs/ferrflow:latest
+  image:
+    name: ghcr.io/ferrlabs/ferrflow:latest
+    entrypoint: [""]
   stage: release
   script:
     - ferrflow release
@@ -20,6 +22,10 @@ release:
       when: on_success
 ```
 
+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'`.
+
+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.
+
 <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>
 </div></aside>
 
@@ -27,7 +33,9 @@ release:
 
 ```yaml
 release:
-  image: ghcr.io/ferrlabs/ferrflow:latest
+  image:
+    name: ghcr.io/ferrlabs/ferrflow:latest
+    entrypoint: [""]
   variables:
     GIT_DEPTH: 0 # historique complet : requis pour le scan des tags
     GITLAB_TOKEN: $CI_JOB_TOKEN
@@ -37,13 +45,21 @@ release:
     - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
 ```
 
+## Utiliser `CI_JOB_TOKEN`
+
+Les exemples ci-dessus passent le token du job via `GITLAB_TOKEN: $CI_JOB_TOKEN`. FerrFlow le reconnaît parce que sa valeur est égale à `CI_JOB_TOKEN`, et s'authentifie comme GitLab l'attend pour un token de job : les appels d'API portent un en-tête `JOB-TOKEN` et git pousse en tant que `gitlab-ci-token`. C'est aussi le cas quand le token du job est passé dans `FERRFLOW_TOKEN`. Tout autre token (token d'accès de projet, de groupe ou personnel) est envoyé en `PRIVATE-TOKEN` et pousse en tant que `oauth2`.
+
+Ce qu'un token de job a le droit de faire se règle par projet dans **Settings > CI/CD > Job token permissions**. Pousser le commit et les tags de release nécessite **Allow Git push requests to the repository**. Quand GitLab refuse un des appels d'API que FerrFlow fait avec un token de job, utilisez plutôt un token d'accès de projet avec le scope `api`.
+
 ## Utiliser un deploy token
 
 Si `CI_JOB_TOKEN` n'a pas les permissions pour pousser des tags, créez un deploy token de projet avec l'accès `write_repository` et stockez-le comme variable CI :
 
 ```yaml
 release:
-  image: ghcr.io/ferrlabs/ferrflow:latest
+  image:
+    name: ghcr.io/ferrlabs/ferrflow:latest
+    entrypoint: [""]
   variables:
     GIT_DEPTH: 0
     GITLAB_TOKEN: $FERRFLOW_DEPLOY_TOKEN # variable CI avec accès write_repository
@@ -55,11 +71,13 @@ release:
 
 ## Commentaires de preview sur les MR
 
-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.
+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.
 
 ```yaml title=".gitlab-ci.yml"
 ferrflow-preview:
-  image: ghcr.io/ferrlabs/ferrflow:latest
+  image:
+    name: ghcr.io/ferrlabs/ferrflow:latest
+    entrypoint: [""]
   stage: test
   variables:
     GIT_DEPTH: 0
@@ -70,10 +88,10 @@ ferrflow-preview:
     - if: $CI_PIPELINE_SOURCE == "merge_request_event"
 ```
 
-Si aucun changement publiable n'est d\u00e9tect\u00e9, le commentaire l'indique.
+Si aucun changement publiable n'est détecté, le commentaire l'indique.
 
 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.
 
 ## GitLab Releases
 
-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.
+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

@@ -3,20 +3,28 @@ title: Configuration
 description: Référence complète du fichier de configuration FerrFlow.
 ---
 
-FerrFlow supporte six formats de fichier de configuration, recherch\u00e9s dans cet ordre :
+FerrFlow supporte six formats de fichier de configuration, recherchés dans cet ordre :
 
 1. `ferrflow.json`
 2. `ferrflow.json5`
 3. `ferrflow.toml`
-4. `ferrflow.ts` (n\u00e9cessite `tsx`)
-5. `ferrflow.js` (n\u00e9cessite `node`)
+4. `ferrflow.ts` (nécessite `tsx`)
+5. `ferrflow.js` (nécessite `node`)
 6. `.ferrflow` (JSON)
 
-Si aucun fichier de configuration n'est trouv\u00e9, FerrFlow d\u00e9tecte automatiquement les fichiers de version courants dans le r\u00e9pertoire actuel.
+Si aucun fichier de configuration n'est trouvé, FerrFlow détecte automatiquement les fichiers de version courants dans le répertoire actuel.
 
 <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>
 </div></aside>
 
+FerrFlow signale toute clé qu'il ne reconnaît pas, quel que soit le format de configuration et y compris dans les fichiers inclus, et propose la clé valide la plus proche quand il y en a une. La clé est ignorée et la commande continue :
+
+```
+Warning: unknown key `workspace.hooks.post-bump` in ferrflow.json, ignored. Did you mean `postBump`?
+```
+
+Sans cet avertissement, une option mal orthographiée ressemble en tout point à une option laissée à sa valeur par défaut : traitez-le comme une erreur dans votre configuration.
+
 ## Formats de configuration
 
 <div class="ferr-tabs">
@@ -88,19 +96,19 @@ format = &quot;toml&quot;
 </div></div>
 </div>
 
-<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>).
-La configuration TOML utilise des cl\u00e9s en <strong>snake_case</strong> (<code>tag_template</code>, <code>versioned_files</code>).
-Toutes les formes sont \u00e9quivalentes.</p>
+<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>).
+La configuration TOML utilise des clés en <strong>snake_case</strong> (<code>tag_template</code>, <code>versioned_files</code>).
+Toutes les formes sont équivalentes.</p>
 </div></aside>
 
 ### Configurations TypeScript et JavaScript
 
-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.
+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.
 
-<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>
+<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>
 </div></aside>
 
-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 :
+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 :
 
 ```ts title="ferrflow.ts"
 export default {
@@ -129,19 +137,19 @@ export default {
 
 #### Objet de contexte des hooks
 
-Les hooks en fonction re\u00e7oivent un objet de contexte avec ces champs :
+Les hooks en fonction reçoivent un objet de contexte avec ces champs :
 
 | Champ          | Type           | Description                                                                  |
 | -------------- | -------------- | ---------------------------------------------------------------------------- |
 | `package`      | string         | Nom du package                                                               |
-| `oldVersion`   | string         | Version avant le bump (vide pour la premi\u00e8re release)                   |
-| `newVersion`   | string         | Version apr\u00e8s le bump                                                   |
+| `oldVersion`   | string         | Version avant le bump (vide pour la première release)                   |
+| `newVersion`   | string         | Version après le bump                                                   |
 | `bumpType`     | string         | `major`, `minor`, `patch`, ou `none`                                         |
 | `tag`          | string         | Nom complet du tag git                                                       |
 | `dryRun`       | boolean        | Vrai si `--dry-run` est actif                                                |
 | `packagePath`  | string         | Chemin absolu vers la racine du package                                      |
-| `channel`      | string ou null | Nom du channel de pr\u00e9-release                                           |
-| `isPrerelease` | boolean        | Vrai si c'est une pr\u00e9-release                                           |
+| `channel`      | string ou null | Nom du channel de pré-release                                           |
+| `isPrerelease` | boolean        | Vrai si c'est une pré-release                                           |
 | `monorepo`     | boolean        | Vrai si c'est une release monorepo                                           |
 | `changelog`    | string         | Section de changelog rendue pour ce bump (markdown)                          |
 | `commits`      | array          | `{ hash, message, type?, scope?, breaking }` par commit du bump              |
@@ -165,7 +173,7 @@ export default {
 };
 ```
 
-Les hooks sous forme de commandes shell et de fonctions peuvent \u00eatre m\u00e9lang\u00e9s dans la m\u00eame config.
+Les hooks sous forme de commandes shell et de fonctions peuvent être mélangés dans la même config.
 
 ## `workspace`