@ferrflow/doc 7.33.4 → 7.34.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -75,21 +75,41 @@ The action writes the key under `RUNNER_TEMP` for the job only, and it never rea
75
75
 
76
76
  ## Accessing the release output
77
77
 
78
- The action exposes the new version as an output you can use in downstream steps:
78
+ In `release` mode the action exposes two outputs:
79
+
80
+ | Output | Value |
81
+ | ---------- | -------------------------------------------------------------------------------------------------------- |
82
+ | `released` | `"true"` when at least one package was tagged, otherwise `"false"`. Always `"false"` on a dry run |
83
+ | `releases` | JSON array of the tagged packages, e.g. `[{"name":"api","version":"1.3.0","tag":"api@v1.3.0"}]`, or `[]` |
84
+
85
+ Gate post-release steps on `released`:
79
86
 
80
87
  ```yaml title=".github/workflows/release.yml"
81
- - uses: FerrLabs/ferrflow@v5
82
- id: ferrflow
88
+ - uses: FerrLabs/ferrflow@v7
89
+ id: release
83
90
  env:
84
91
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
85
92
 
86
- - name: Build Docker image
87
- if: steps.ferrflow.outputs.version != ''
93
+ - name: Publish
94
+ if: steps.release.outputs.released == 'true'
95
+ run: npm publish
96
+ ```
97
+
98
+ In a monorepo, read `releases` to act on each package that went out:
99
+
100
+ ```yaml title=".github/workflows/release.yml"
101
+ - name: Build released packages
102
+ if: steps.release.outputs.released == 'true'
103
+ env:
104
+ RELEASES: ${{ steps.release.outputs.releases }}
88
105
  run: |
89
- docker build -t myimage:${{ steps.ferrflow.outputs.version }} .
90
- docker push myimage:${{ steps.ferrflow.outputs.version }}
106
+ echo "$RELEASES" | jq -r '.[].name' | while read -r pkg; do
107
+ pnpm --filter "$pkg" build
108
+ done
91
109
  ```
92
110
 
111
+ With `releaseCommitMode: "pr"`, the run that only opens the release pull request tags nothing and reports `released=false`. The run that tags the merged release reports it.
112
+
93
113
  ## Skip CI on release commits
94
114
 
95
115
  FerrFlow commits version bumps with `[skip ci]` in the message by default to prevent infinite loops. No extra configuration needed.
@@ -108,3 +108,24 @@ If you store that token as a **protected** variable, GitLab only exposes it to p
108
108
  ## GitLab Releases
109
109
 
110
110
  When `GITLAB_TOKEN` is set, FerrFlow creates a GitLab Release with the generated changelog as release notes, matching the behaviour of the GitHub integration.
111
+
112
+ ## Gating later jobs on a release
113
+
114
+ `--output-format dotenv` writes `FERRFLOW_RELEASED` and `FERRFLOW_RELEASES` (a JSON array of `name`, `version`, `tag`) to a file GitLab can pass to later jobs:
115
+
116
+ ```yaml title=".gitlab-ci.yml"
117
+ release:
118
+ script:
119
+ - ferrflow release --output-format dotenv --output-file ferrflow.env
120
+ artifacts:
121
+ reports:
122
+ dotenv: ferrflow.env
123
+
124
+ build:
125
+ needs: [release]
126
+ script:
127
+ - if [ "$FERRFLOW_RELEASED" != "true" ]; then exit 0; fi
128
+ - pnpm build
129
+ ```
130
+
131
+ Dotenv variables reach the script of a later job, not its `rules:`, which GitLab evaluates when the pipeline is created.
@@ -287,6 +287,8 @@ floating_tags = ["major"]
287
287
 
288
288
  When releasing `v1.2.3`, FerrFlow creates or moves a `v1` tag pointing to the same commit. With `["major", "minor"]`, both `v1` and `v1.2` tags are maintained.
289
289
 
290
+ A level only applies when it is shorter than the version itself. With `sequential` versioning the release tag is already `v4`, so `"major"` creates nothing, and a `{year}.{seq}` version such as `2026.3` gets a `2026` alias but no minor one. A numeric tag counts as a floating tag only when a longer release tag under the same prefix extends it (`v1` next to `v1.2.3`), so sequential and two-part release tags are always read as releases.
291
+
290
292
  If a floating tag would move backward (e.g. releasing a `v1.1.0` hotfix when `v1.2.0` already exists), FerrFlow blocks the release. Use `--force` to override this check.
291
293
 
292
294
  ### Orphaned tag strategy
@@ -11,13 +11,15 @@ Run the full release pipeline: bump versions, update changelogs, commit, tag, pu
11
11
  ferrflow release [OPTIONS]
12
12
  ```
13
13
 
14
- | Flag | Description |
15
- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
16
- | `--force` | Allow floating tags to move backward to a lower version |
17
- | `--force-version <VERSION>` | Force a specific version, skipping commit analysis. Format: `VERSION` (single repo) or `NAME@VERSION` (monorepo) |
18
- | `--channel <NAME>` | Pre-release channel override (e.g. `beta`, `rc`, `dev`) |
19
- | `--draft` | Create releases as drafts (GitHub only). A later `ferrflow release` without `--draft` detects and publishes existing drafts automatically |
20
- | `--force-unlock` | Break an existing `.git/ferrflow.lock` before acquiring it. Use only when no other `ferrflow release` is running — e.g. after a crash left the lockfile behind |
14
+ | Flag | Description |
15
+ | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
16
+ | `--force` | Allow floating tags to move backward to a lower version |
17
+ | `--force-version <VERSION>` | Force a specific version, skipping commit analysis. Format: `VERSION` (single repo) or `NAME@VERSION` (monorepo) |
18
+ | `--channel <NAME>` | Pre-release channel override (e.g. `beta`, `rc`, `dev`) |
19
+ | `--draft` | Create releases as drafts (GitHub only). A later `ferrflow release` without `--draft` detects and publishes existing drafts automatically |
20
+ | `--force-unlock` | Break an existing `.git/ferrflow.lock` before acquiring it. Use only when no other `ferrflow release` is running — e.g. after a crash left the lockfile behind |
21
+ | `--output-format <FORMAT>` | After the run, write whether a release happened and which packages were tagged: `github` (appends to `$GITHUB_OUTPUT`), `dotenv` (`FERRFLOW_RELEASED` / `FERRFLOW_RELEASES`), or `json` |
22
+ | `--output-file <PATH>` | Destination for `--output-format`. Required for `dotenv` and `json`; `github` defaults to `$GITHUB_OUTPUT` |
21
23
 
22
24
  **What it does:**
23
25
 
@@ -75,21 +75,41 @@ L'action écrit la clé sous `RUNNER_TEMP`, le temps du job, et elle n'atteint n
75
75
 
76
76
  ## Accéder à la sortie de la release
77
77
 
78
- L'action expose la nouvelle version en output que vous pouvez utiliser dans les étapes suivantes :
78
+ En mode `release`, l'action expose deux outputs :
79
+
80
+ | Output | Valeur |
81
+ | ---------- | -------------------------------------------------------------------------------------------------------------- |
82
+ | `released` | `"true"` si au moins un package a été tagué, sinon `"false"`. Toujours `"false"` en dry run |
83
+ | `releases` | Tableau JSON des packages tagués, par exemple `[{"name":"api","version":"1.3.0","tag":"api@v1.3.0"}]`, ou `[]` |
84
+
85
+ Conditionnez les étapes post-release sur `released` :
79
86
 
80
87
  ```yaml
81
- - uses: FerrLabs/ferrflow@v5
82
- id: ferrflow
88
+ - uses: FerrLabs/ferrflow@v7
89
+ id: release
83
90
  env:
84
91
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
85
92
 
86
- - name: Build Docker image
87
- if: steps.ferrflow.outputs.version != ''
93
+ - name: Publish
94
+ if: steps.release.outputs.released == 'true'
95
+ run: npm publish
96
+ ```
97
+
98
+ Dans un monorepo, lisez `releases` pour agir sur chaque package publié :
99
+
100
+ ```yaml
101
+ - name: Build released packages
102
+ if: steps.release.outputs.released == 'true'
103
+ env:
104
+ RELEASES: ${{ steps.release.outputs.releases }}
88
105
  run: |
89
- docker build -t myimage:${{ steps.ferrflow.outputs.version }} .
90
- docker push myimage:${{ steps.ferrflow.outputs.version }}
106
+ echo "$RELEASES" | jq -r '.[].name' | while read -r pkg; do
107
+ pnpm --filter "$pkg" build
108
+ done
91
109
  ```
92
110
 
111
+ Avec `releaseCommitMode: "pr"`, le run qui ouvre seulement la pull request de release ne tague rien et renvoie `released=false`. C'est le run qui tague la release mergée qui la signale.
112
+
93
113
  ## Skip CI sur les commits de release
94
114
 
95
115
  FerrFlow ajoute `[skip ci]` dans le message des commits de version par défaut pour éviter les boucles infinies. Aucune configuration supplémentaire nécessaire.
@@ -95,3 +95,24 @@ Si vous stockez ce token dans une variable **protégée**, GitLab ne l'expose qu
95
95
  ## GitLab Releases
96
96
 
97
97
  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.
98
+
99
+ ## Conditionner les jobs suivants à une release
100
+
101
+ `--output-format dotenv` écrit `FERRFLOW_RELEASED` et `FERRFLOW_RELEASES` (un tableau JSON de `name`, `version`, `tag`) dans un fichier que GitLab transmet aux jobs suivants :
102
+
103
+ ```yaml
104
+ release:
105
+ script:
106
+ - ferrflow release --output-format dotenv --output-file ferrflow.env
107
+ artifacts:
108
+ reports:
109
+ dotenv: ferrflow.env
110
+
111
+ build:
112
+ needs: [release]
113
+ script:
114
+ - if [ "$FERRFLOW_RELEASED" != "true" ]; then exit 0; fi
115
+ - pnpm build
116
+ ```
117
+
118
+ Les variables dotenv arrivent dans le script d'un job suivant, pas dans ses `rules:`, que GitLab évalue à la création du pipeline.
@@ -18,6 +18,8 @@ ferrflow release [OPTIONS]
18
18
  | `--channel <NAME>` | Canal de pré-release à utiliser (ex. `beta`, `rc`, `dev`) |
19
19
  | `--draft` | Créer les releases en brouillon (GitHub uniquement). Un `ferrflow release` ultérieur sans `--draft` détecte et publie automatiquement les brouillons existants |
20
20
  | `--force-unlock` | Forcer la levée d'un verrou `.git/ferrflow.lock` existant. À n'utiliser que si aucun autre `ferrflow release` n'est en cours : par exemple après un crash ayant laissé le fichier de verrou |
21
+ | `--output-format <FORMAT>` | Après le run, écrire si une release a eu lieu et quels packages ont été tagués : `github` (ajouté à `$GITHUB_OUTPUT`), `dotenv` (`FERRFLOW_RELEASED` / `FERRFLOW_RELEASES`) ou `json` |
22
+ | `--output-file <PATH>` | Destination de `--output-format`. Obligatoire pour `dotenv` et `json` ; `github` utilise `$GITHUB_OUTPUT` par défaut |
21
23
 
22
24
  **Ce que ça fait :**
23
25
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ferrflow/doc",
3
- "version": "7.33.4",
3
+ "version": "7.34.1",
4
4
  "description": "Documentation for FerrFlow, the universal semantic versioning CLI. Rendered at ferrflow.com/docs.",
5
5
  "license": "MIT",
6
6
  "repository": {