Configuration

FerrFlow supporte six formats de fichier de configuration, recherch\u00e9s dans cet ordre :

1. ferrflow.json
2. ferrflow.json5
3. ferrflow.toml
4. ferrflow.ts (n\u00e9cessite tsx)
5. ferrflow.js (n\u00e9cessite 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.

Astuce

Ajoutez "$schema": "https://ferrflow.com/schema/ferrflow.json" à votre configuration JSON pour l’autocomplétion et la validation dans votre éditeur.

Formats de configuration

TypeScript

ferrflow.ts

export default {
  workspace: {
    tagTemplate: "v{version}",
  },
  package: [
    {
      name: "my-app",
      path: ".",
      changelog: "CHANGELOG.md",
      versionedFiles: [
        { path: "Cargo.toml", format: "toml" },
      ],
    },
  ],
};

JSON

{
  "$schema": "https://ferrflow.com/schema/ferrflow.json",
  "workspace": {
    "tagTemplate": "v{version}"
  },
  "package": [
    {
      "name": "my-app",
      "path": ".",
      "changelog": "CHANGELOG.md",
      "versionedFiles": [
        { "path": "Cargo.toml", "format": "toml" }
      ]
    }
  ]
}

TOML

[workspace]
tag_template = "v{version}"

[[package]]
name = "my-app"
path = "."
changelog = "CHANGELOG.md"

[[package.versioned_files]]
path = "Cargo.toml"
format = "toml"

JSON5

{
  $schema: "https://ferrflow.com/schema/ferrflow.json",
  workspace: {
    tagTemplate: "v{version}",
  },
  package: [
    {
      name: "my-app",
      path: ".",
      changelog: "CHANGELOG.md",
      versionedFiles: [
        { path: "Cargo.toml", format: "toml" },
      ],
    },
  ],
}

YAML

workspace:
  tagTemplate: "v{version}"

package:
  - name: my-app
    path: "."
    changelog: CHANGELOG.md
    versionedFiles:
      - path: Cargo.toml
        format: toml

Note

Les configurations JSON, JSON5, et TypeScript/JavaScript utilisent des cl\u00e9s en camelCase (tagTemplate, versionedFiles). La configuration TOML utilise des cl\u00e9s en snake_case (tag_template, versioned_files). Les configurations YAML supportent les deux, mais camelCase est recommand\u00e9 pour la coh\u00e9rence avec JSON. Toutes les formes sont \u00e9quivalentes.

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.

Attention

Les configs TypeScript n\u00e9cessitent tsx (npm install -g tsx). Les configs JavaScript n\u00e9cessitent node (v18+).

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 :

ferrflow.ts

export default {
  workspace: {
    tagTemplate: "v{version}",
    hooks: {
      postPublish: async (ctx) => {
        await fetch("https://hooks.slack.com/services/...", {
          method: "POST",
          body: JSON.stringify({
            text: `Released ${ctx.package}@${ctx.newVersion}`,
          }),
        });
      },
    },
  },
  package: [
    {
      name: "my-app",
      path: ".",
      versionedFiles: [{ path: "package.json", format: "json" }],
    },
  ],
};

Objet de contexte des hooks

Les hooks en fonction re\u00e7oivent 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
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

Les hooks sous forme de commandes shell et de fonctions peuvent \u00eatre m\u00e9lang\u00e9s dans la m\u00eame config.

workspace

Paramètres globaux qui s’appliquent à tous les packages.

Champ	Type	Défaut	Description
remote	string	"origin"	Remote git vers lequel pousser
branch	string	auto-détecté	Branche vers laquelle pousser (détectée depuis le HEAD du remote)
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.
versioning	string	"semver"	Stratégie de versionnage par défaut pour tous les packages
releaseCommitMode	string	"commit"	Gestion du commit de release : "commit", "pr" ou "none"
skipCi	boolean	dépend du mode	Ajouter [skip ci] aux commits de release. Par défaut true en mode "commit", false sinon.
autoMergeReleases	boolean	true	Activer l’auto-merge sur les PR de release (uniquement en mode "pr")
recoverMissedReleases	boolean	false	Lorsqu’activé, si FerrFlow trouve des commits non publiés couvrant plusieurs incréments de version, il crée toutes les releases intermédiaires au lieu de sauter directement à la dernière version
telemetry	boolean	true	Envoyer des données de télémétrie anonymes

Modèle de tag

Le champ tagTemplate contrôle le nommage des tags git. Placeholders disponibles :

Placeholder	Description
{version}	Le numéro de version (ex. 1.2.3)
{name}	Le nom du package

JSON

ferrflow.json

{
  "workspace": {
    "tagTemplate": "v{version}"
  }
}

TOML

ferrflow.toml

[workspace]
tag_template = "v{version}"

JSON5

ferrflow.json5

{
  workspace: {
    tagTemplate: "v{version}",
  },
}

YAML

ferrflow.yaml

workspace:
  tagTemplate: "v{version}"

Pour les monorepos, utilisez {name} pour namespacer les tags par package :

JSON

ferrflow.json

{
  "workspace": {
    "tagTemplate": "{name}@v{version}"
  }
}

TOML

ferrflow.toml

[workspace]
tag_template = "{name}@v{version}"

JSON5

ferrflow.json5

{
  workspace: {
    tagTemplate: "{name}@v{version}",
  },
}

YAML

ferrflow.yaml

workspace:
  tagTemplate: "{name}@v{version}"

Mode de commit de release

Contrôle la façon dont FerrFlow gère le commit qui met à jour les fichiers de version et les changelogs.

Mode	Comportement
"commit"	Commit directement sur la branche courante et pousse (par défaut)
"pr"	Crée une branche release/ et ouvre une pull request
"none"	Crée uniquement les tags et les releases, ne commit pas les changements de fichiers

JSON

ferrflow.json

{
  "workspace": {
    "releaseCommitMode": "pr",
    "autoMergeReleases": true
  }
}

TOML

ferrflow.toml

[workspace]
release_commit_mode = "pr"
auto_merge_releases = true

JSON5

ferrflow.json5

{
  workspace: {
    releaseCommitMode: "pr",
    autoMergeReleases: true,
  },
}

YAML

ferrflow.yaml

workspace:
  releaseCommitMode: pr
  autoMergeReleases: true

Stratégies de versionnage

FerrFlow supporte plusieurs stratégies de versionnage, configurables au niveau du workspace ou du package.

Stratégie	Format	Progression exemple
semver	MAJOR.MINOR.PATCH	1.2.3 → 1.3.0 → 2.0.0
calver	YYYY.MM.PATCH	2026.03.0 → 2026.03.1 → 2026.04.0
calver-short	YY.MM.PATCH	26.03.0 → 26.03.1
calver-seq	YYYY.MM.SEQ	2026.03.1 → 2026.03.2
sequential	N	1 → 2 → 3
zerover	0.MINOR.PATCH	0.1.0 → 0.2.0 (n’atteint jamais 1.0)

JSON

ferrflow.json

{
  "workspace": {
    "versioning": "calver"
  }
}

TOML

ferrflow.toml

[workspace]
versioning = "calver"

JSON5

ferrflow.json5

{
  workspace: {
    versioning: "calver",
  },
}

YAML

ferrflow.yaml

workspace:
  versioning: calver

package

Définit un package à versionner. Vous pouvez en avoir un ou plusieurs.

Champ	Requis	Défaut	Description
name	oui	—	Identifiant du package, utilisé dans le préfixe du tag git
path	oui	—	Chemin relatif vers le répertoire du package
changelog	non	{path}/CHANGELOG.md	Chemin vers le fichier changelog
sharedPaths	non	[]	Chemins qui déclenchent ce package lorsqu’ils sont modifiés
versioning	non	hérité du workspace	Surcharger la stratégie de versionnage pour ce package
tagTemplate	non	hérité du workspace	Surcharger le modèle de tag pour ce package

versionedFiles

Fichiers dans lesquels le numéro de version doit être mis à jour.

JSON

ferrflow.json

{
  "package": [
    {
      "name": "my-app",
      "path": ".",
      "versionedFiles": [
        { "path": "Cargo.toml", "format": "toml" },
        { "path": "npm/package.json", "format": "json" }
      ]
    }
  ]
}

TOML

ferrflow.toml

[[package]]
name = "my-app"
path = "."

[[package.versioned_files]]
path = "Cargo.toml"
format = "toml"

[[package.versioned_files]]
path = "npm/package.json"
format = "json"

JSON5

ferrflow.json5

{
  package: [
    {
      name: "my-app",
      path: ".",
      versionedFiles: [
        { path: "Cargo.toml", format: "toml" },
        { path: "npm/package.json", format: "json" },
      ],
    },
  ],
}

YAML

ferrflow.yaml

package:
  - name: my-app
    path: "."
    versionedFiles:
      - path: Cargo.toml
        format: toml
      - path: npm/package.json
        format: json

format	Fichier	Champ mis à jour
toml	Cargo.toml, pyproject.toml	[package].version ou [project].version
json	package.json	version
xml	pom.xml	Premier élément <version>
gradle	build.gradle, build.gradle.kts	version = "..."
helm	Chart.yaml	version et appVersion (si présent)
gomod	go.mod	Pas de mise à jour de fichier — la version vient uniquement des tags git
txt	VERSION, VERSION.txt	Contenu entier du fichier remplacé

hooks

Exécutez des commandes shell à des points clés du cycle de release. Les hooks peuvent être définis au niveau du workspace (par défaut pour tous les packages) ou par package (surcharge les hooks du workspace pour ce package).

Cycle de vie

calcul du bump
  ↓
pre_bump        ← valider l'état, vérifier les prérequis
  ↓
écriture des fichiers de version
  ↓
post_bump       ← modifier des fichiers supplémentaires avec la nouvelle version
  ↓
génération du changelog
  ↓
pre_commit      ← vérifier les changements stagés, lancer les linters
  ↓
git commit + tag
  ↓
pre_publish     ← lancer les tests sur le commit taggé, builder les artefacts
  ↓
git push + création de la release
  ↓
post_publish    ← pousser les images Docker, notifier Slack, publier les packages

Configuration

JSON

{
  "workspace": {
    "hooks": {
      "preBump": "cargo test",
      "postBump": "node scripts/sync-deps.js",
      "preCommit": "cargo fmt --check",
      "prePublish": "cargo build --release",
      "postPublish": "make docker-push && ./scripts/notify.sh",
      "onFailure": "abort"
    }
  }
}

TOML

[hooks]
pre_bump     = "cargo test"
post_bump    = "node scripts/sync-deps.js"
pre_commit   = "cargo fmt --check"
pre_publish  = "cargo build --release"
post_publish = "make docker-push && ./scripts/notify.sh"
on_failure   = "abort"

JSON5

{
  workspace: {
    hooks: {
      preBump: "cargo test",
      postBump: "node scripts/sync-deps.js",
      preCommit: "cargo fmt --check",
      prePublish: "cargo build --release",
      postPublish: "make docker-push && ./scripts/notify.sh",
      onFailure: "abort",
    },
  },
}

YAML

workspace:
  hooks:
    preBump: cargo test
    postBump: node scripts/sync-deps.js
    preCommit: cargo fmt --check
    prePublish: cargo build --release
    postPublish: "make docker-push && ./scripts/notify.sh"
    onFailure: abort

Champ	Type	Défaut	Description
preBump	string	—	Exécuté après le calcul du bump, avant l’écriture des fichiers de version
postBump	string	—	Exécuté après l’écriture des fichiers de version
preCommit	string	—	Exécuté après le changelog, avant le commit git
prePublish	string	—	Exécuté après le commit+tag, avant le push
postPublish	string	—	Exécuté après le push et la création de la release
onFailure	string	"abort"	"abort" annule la release en cas d’échec, "continue" affiche un avertissement

Variables d’environnement

Chaque hook reçoit ces variables :

Variable	Description	Exemple
FERRFLOW_PACKAGE	Nom du package	api
FERRFLOW_OLD_VERSION	Version avant le bump (vide pour la première release)	1.2.3
FERRFLOW_NEW_VERSION	Version après le bump	1.3.0
FERRFLOW_BUMP_TYPE	major, minor, patch ou none	minor
FERRFLOW_TAG	Nom complet du tag git	api@v1.3.0
FERRFLOW_DRY_RUN	true si --dry-run est activé	false
FERRFLOW_PACKAGE_PATH	Chemin absolu vers la racine du package	/home/user/repo/packages/api

Hooks par package

Les hooks au niveau du package remplacent les hooks du workspace pour ce package (ils ne sont pas fusionnés).

JSON

{
  "workspace": {
    "hooks": {
      "preBump": "echo releasing $FERRFLOW_PACKAGE",
      "postPublish": "make notify"
    }
  },
  "package": [
    {
      "name": "api",
      "path": "packages/api",
      "hooks": {
        "preBump": "cargo test"
      }
    }
  ]
}

TOML

[hooks]
pre_bump     = "echo releasing $FERRFLOW_PACKAGE"
post_publish = "make notify"

[[package]]
name = "api"
path = "packages/api"

[package.hooks]
pre_bump = "cargo test"

JSON5

{
  workspace: {
    hooks: {
      preBump: "echo releasing $FERRFLOW_PACKAGE",
      postPublish: "make notify",
    },
  },
  package: [
    {
      name: "api",
      path: "packages/api",
      hooks: {
        preBump: "cargo test",
      },
    },
  ],
}

YAML

workspace:
  hooks:
    preBump: "echo releasing $FERRFLOW_PACKAGE"
    postPublish: make notify

package:
  - name: api
    path: packages/api
    hooks:
      preBump: cargo test

Dans cet exemple, le package api exécute cargo test pour preBump (surchargeant l’echo du workspace) mais hérite du hook postPublish du workspace.

Comportement

• --dry-run : les hooks sont affichés mais non exécutés.
• --verbose : la sortie stdout/stderr des hooks est diffusée en direct. Sinon, la sortie n’est affichée qu’en cas d’échec.
• Les fichiers modifiés par les hooks postBump ou preCommit sont automatiquement inclus dans le commit de release.

Exemples complets

Repo unique

JSON

ferrflow.json

{
  "$schema": "https://ferrflow.com/schema/ferrflow.json",
  "workspace": {
    "tagTemplate": "v{version}"
  },
  "package": [
    {
      "name": "ferrflow",
      "path": ".",
      "changelog": "CHANGELOG.md",
      "versionedFiles": [
        { "path": "Cargo.toml", "format": "toml" },
        { "path": "npm/package.json", "format": "json" }
      ]
    }
  ]
}

TOML

ferrflow.toml

[workspace]
tag_template = "v{version}"

[[package]]
name = "ferrflow"
path = "."
changelog = "CHANGELOG.md"

[[package.versioned_files]]
path = "Cargo.toml"
format = "toml"

[[package.versioned_files]]
path = "npm/package.json"
format = "json"

JSON5

ferrflow.json5

{
  $schema: "https://ferrflow.com/schema/ferrflow.json",
  workspace: {
    tagTemplate: "v{version}",
  },
  package: [
    {
      name: "ferrflow",
      path: ".",
      changelog: "CHANGELOG.md",
      versionedFiles: [
        { path: "Cargo.toml", format: "toml" },
        { path: "npm/package.json", format: "json" },
      ],
    },
  ],
}

YAML

ferrflow.yaml

workspace:
  tagTemplate: "v{version}"

package:
  - name: ferrflow
    path: "."
    changelog: CHANGELOG.md
    versionedFiles:
      - path: Cargo.toml
        format: toml
      - path: npm/package.json
        format: json

Monorepo

JSON

ferrflow.json

{
  "$schema": "https://ferrflow.com/schema/ferrflow.json",
  "workspace": {
    "tagTemplate": "{name}@v{version}"
  },
  "package": [
    {
      "name": "api",
      "path": "packages/api",
      "changelog": "packages/api/CHANGELOG.md",
      "sharedPaths": ["packages/shared/"],
      "versionedFiles": [
        { "path": "packages/api/Cargo.toml", "format": "toml" }
      ]
    },
    {
      "name": "site",
      "path": "packages/site",
      "changelog": "packages/site/CHANGELOG.md",
      "sharedPaths": ["packages/shared/"],
      "versionedFiles": [
        { "path": "packages/site/package.json", "format": "json" }
      ]
    }
  ]
}

TOML

ferrflow.toml

[workspace]
tag_template = "{name}@v{version}"

[[package]]
name = "api"
path = "packages/api"
changelog = "packages/api/CHANGELOG.md"
shared_paths = ["packages/shared/"]

[[package.versioned_files]]
path = "packages/api/Cargo.toml"
format = "toml"

[[package]]
name = "site"
path = "packages/site"
changelog = "packages/site/CHANGELOG.md"
shared_paths = ["packages/shared/"]

[[package.versioned_files]]
path = "packages/site/package.json"
format = "json"

JSON5

ferrflow.json5

{
  $schema: "https://ferrflow.com/schema/ferrflow.json",
  workspace: {
    tagTemplate: "{name}@v{version}",
  },
  package: [
    {
      name: "api",
      path: "packages/api",
      changelog: "packages/api/CHANGELOG.md",
      sharedPaths: ["packages/shared/"],
      versionedFiles: [
        { path: "packages/api/Cargo.toml", format: "toml" },
      ],
    },
    {
      name: "site",
      path: "packages/site",
      changelog: "packages/site/CHANGELOG.md",
      sharedPaths: ["packages/shared/"],
      versionedFiles: [
        { path: "packages/site/package.json", format: "json" },
      ],
    },
  ],
}

YAML

ferrflow.yaml

workspace:
  tagTemplate: "{name}@v{version}"

package:
  - name: api
    path: packages/api
    changelog: packages/api/CHANGELOG.md
    sharedPaths:
      - packages/shared/
    versionedFiles:
      - path: packages/api/Cargo.toml
        format: toml

  - name: site
    path: packages/site
    changelog: packages/site/CHANGELOG.md
    sharedPaths:
      - packages/shared/
    versionedFiles:
      - path: packages/site/package.json
        format: json

Astuce

Exécutez ferrflow init pour générer automatiquement un fichier de configuration basé sur ce que FerrFlow détecte dans votre repo.