---
title: Stabilité & compatibilité
description: Ce que couvre la promesse SemVer 1.0 de gwm, ce qu'elle laisse délibérément libre d'évoluer, la politique MSRV et la conduite des dépréciations.
navigation:
title: Stabilité
---
# Stabilité & compatibilité
gwm suit le [versionnage sémantique](https://semver.org/lang/fr/)
(`MAJEUR.MINEUR.CORRECTIF`). Cette page est le contrat de compatibilité
explicite et publié qui adosse la ligne `1.0` : elle énonce quelles surfaces
sont couvertes par cette promesse (un changement cassant y force une version
**majeure**) et lesquelles restent délibérément libres d'évoluer en
**mineure** ou en **correctif**.
La règle générale : tout ce qu'une *machine* parse est couvert ; tout ce qu'un
*humain* lit à l'écran ne l'est pas.
## Couvert par SemVer (changement cassant → majeure)
Ces surfaces font partie du contrat public. Un changement rétro-incompatible —
renommer ou supprimer un élément, ou changer son type ou sa signification
documentée — est une décision consciente de version **majeure**.
- **Surface CLI** — les sous-commandes, leurs flags et la forme documentée de
leurs arguments. Ajouter une sous-commande ou un flag optionnel est additif
(mineure) ; en renommer ou en supprimer un est cassant.
- **Codes de sortie** — le contrat déterministe `0` / `1` / `2` documenté par
commande (ex. le code dérivé de la sévérité de `gwm doctor`). Les scripts et
jobs CI s'y appuient, donc la signification d'un code est gelée sous cette
promesse.
- **Schémas de sortie `--format=json`** — les payloads JSON de `gwm list`,
`gwm doctor`, `gwm path` et `gwm status --json`, documentés sous
[`docs/schema/`](https://github.com/kbrdn1/gwm-cli/tree/main/docs/schema)
et figés par `tests/contract_tests.rs`.
- **Protocole daemon JSON-RPC 2.0** — les méthodes `list` / `doctor` /
`path` / `subscribe`, la notification `worktrees.changed` et les codes
d'erreur JSON-RPC standard. Un résultat `list` du daemon est octet-pour-octet
identique à `gwm list --format=json`, donc les deux partagent un unique
`SCHEMA_VERSION`.
- **Schéma `.gwm.toml`** — l'ensemble des sections de premier niveau
(`worktree`, `bootstrap`, `hooks`, `doctor`, `tui`, `theme`, `git_tui`,
`review`, `labels`, `milestones`, `branch_types`, `aliases`, `gitmoji`,
`issue_template`, `pr_template`, `exec`, `clean`). Une section stable
renommée ou supprimée est cassante.
### Gelé par un test vs. couvert par la promesse
Trois de ces surfaces sont gelées *mécaniquement* — un renommage casse la CI
avant de pouvoir être publié : les **schémas JSON**, les **noms de
méthodes/notification du daemon** et l'**ensemble des sections `.gwm.toml`**,
tous figés par `tests/contract_tests.rs` face à la source de vérité unique de
[`src/contract.rs`](https://github.com/kbrdn1/gwm-cli/blob/main/src/contract.rs).
Les **sous-commandes/flags CLI** et les **significations des codes de sortie**
ne sont *pas* figés par un test de bout en bout (seul le champ `exit_code` de
`doctor` ride le schéma JSON) ; ils sont couverts par cette promesse SemVer
écrite et revus à chaque PR. Considère-les comme tout aussi contraignants —
l'absence de test garde-fou n'autorise pas à les casser en silence.
### Le détail du contrat machine vit ailleurs
Les paliers par champ (quels champs exacts sont **stables** vs
**expérimentaux**), le mécanisme de détection de dérive (`SCHEMA_VERSION` sur
la notification daemon, `gwm --version` pour les consommateurs CLI one-shot)
et les règles `additionalProperties` sont documentés en entier dans
[`docs/schema/README.md`](https://github.com/kbrdn1/gwm-cli/blob/main/docs/schema/README.md).
Notamment, quelques champs sont **expérimentaux** et peuvent changer sans bump
majeur — ex. le champ `repo` propre au mode workspace sur une ligne `list` et
le `repo` de premier niveau sur `status --json`. En cas de doute sur un champ
précis, cette table de paliers fait foi.
## NON couvert par SemVer (peut changer en mineure/correctif)
Ces surfaces sont libres de changer sans bump majeur. Ne construis pas
d'automatisation par-dessus.
- **Disposition & couleurs de la TUI** — agencement des panneaux, placement
des widgets, le thème / la palette, et tout détail visuel de l'interface
ratatui. Scripter contre la TUI rendue n'est pas supporté.
- **Chaînes lisibles par un humain** — lignes de log, messages de la barre de
statut, blurbs d'aide, la sortie humaine (non `--format=json`) de n'importe
quelle commande. Parse plutôt la surface JSON ; la prose peut être reformulée
à tout moment.
- **API Rust interne** — gwm est livré comme binaire, pas comme crate
bibliothèque publiée. Les éléments `pub` de `src/` existent pour la suite de
tests et la réutilisation interne ; ils ne forment pas une API stable et ne
portent aucune garantie SemVer.
## Politique MSRV
La version Rust minimale supportée est déclarée via `rust-version` dans
[`Cargo.toml`](https://github.com/kbrdn1/gwm-cli/blob/main/Cargo.toml)
(actuellement **1.86**) — le plancher contre lequel la crate est censée
compiler. La CI build et teste sur la toolchain *stable* ; elle n'épingle pas
de job 1.86 dédié, donc le MSRV est vérifié localement avant un bump avec
`cargo clippy --all-targets -- -W clippy::incompatible_msrv` (ou
`cargo msrv verify`), qui signale l'usage accidentel d'une API plus récente
que le plancher déclaré.
En pratique, un bump MSRV ride une release **mineure**, pas majeure — il a
historiquement été piloté par une dépendance relevant son propre plancher (le
bump `1.86` est arrivé avec `tui-term` / `portable-pty` lors de l'ajout de
l'overlay PTY), et est traité comme une mise à jour de toolchain de routine
plutôt qu'un changement cassant du contrat public. Les bumps sont signalés
dans le changelog pour que les packagers ne soient pas surpris.
## Processus de dépréciation
Quand une surface couverte doit changer de façon rétro-incompatible :
1. **Annoncer** — documenter la dépréciation dans le changelog, sous la
release qui l'introduit, et (lorsque la surface le permet) émettre un
avertissement à l'exécution pointant vers le remplaçant.
2. **Garder l'ancien chemin fonctionnel** pendant le reste de la ligne majeure
courante — une dépréciation est un préavis, pas une suppression immédiate.
3. **Supprimer uniquement sur un bump majeur**, la suppression étant listée
dans les notes de cette release avec le chemin de migration.
Les changements additifs (nouvelle sous-commande, flag optionnel, nouveau
champ JSON optionnel, nouvelle méthode daemon) ne sont **pas** des
dépréciations — ils sont livrés en release mineure et ne nécessitent aucun
avertissement, car les consommateurs existants continuent de fonctionner
inchangés (les consommateurs DOIVENT ignorer les champs JSON inconnus).
## Voir aussi
- [`docs/schema/README.md`](https://github.com/kbrdn1/gwm-cli/blob/main/docs/schema/README.md)
— les paliers stable/expérimental par champ et le contrat de détection de
dérive.
- [`src/contract.rs`](https://github.com/kbrdn1/gwm-cli/blob/main/src/contract.rs)
— la source de vérité unique pour `SCHEMA_VERSION` et les ensembles gelés de
méthodes/sections.
- [Contribuer → Releases](/fr/development/contributing) et
[`CONTRIBUTING.md`](https://github.com/kbrdn1/gwm-cli/blob/main/CONTRIBUTING.md)
— le processus de release SemVer et le workflow de tag.