---
title: Contribuer
description: Gitmoji + Conventional Commits, nommage des branches, checklist de PR, règles de séparation du CHANGELOG.
---
# Contribuer
Cette page résume les conventions de contribution du repo. La version longue complète vit dans [`CONTRIBUTING.md`](https://github.com/kbrdn1/gwm-cli/blob/main/CONTRIBUTING.md) à la racine du repo ; cette page existe pour que le site de docs puisse porter la même information sans forker la source de vérité.
## nommage des branches
```
<type>/#<issue>-<short-description>
```
Exemples :
```
feat/#42-user-auth
fix/#117-leak
docs/#77-sync-v0-6-0-docs
chore/#56-precommit-hook
```
- `<type>` — l'un de `feat`, `fix`, `hotfix`, `docs`, `test`, `refactor`, `chore`, `perf`, `ci`, `build`.
- `<issue>` — le numéro d'issue GitHub (chiffres uniquement). Une issue par branche garde l'auto-link opérationnel (voir [linking GitHub](/fr/integrations/github-linking#détection-automatique)).
- `<short-description>` — en kebab-case, ~3-4 mots, normalisée automatiquement par `gwm create`.
Ne travaillez jamais directement sur `main` ou `dev`. `gwm create <type> <N> <slug>` produit une branche + un worktree conformes en une seule étape.
## format de commit
Gitmoji + Conventional Commits — un commit par préoccupation, atomique, descriptif :
```
<emoji> <type>(<scope>)<!>: <subject>
<body — optional, wrap at 72>
refs #N ← intermediate commits
closes #N ← ONLY on the last commit of the series
```
### tableau emoji + type
| ✨ | `feat` | nouvelle capacité |
| 🐛 | `fix` | correction de bug |
| ♻️ | `refactor` | restructuration sans changement de comportement |
| ✅ | `test` | tests ajoutés ou corrigés |
| 📝 | `docs` | README / CHANGELOG / doc inline / cet arbre même |
| 🔧 | `chore` | outillage, config, deps |
| 🏗️ | `build` | release / cut / bump de version |
| 👷 | `ci` | workflows |
| ⚡ | `perf` | amélioration de performance mesurée |
| 🚑️ | `hotfix` | correction urgente publiée hors de la cadence normale de release |
| 🔥 | `chore(remove)` | code mort / suppression de fichier |
| ⬆️ | `chore(bump)` | bump de dépendance |
| 🔒 | `security` | correction touchant à la sécurité |
### scopes (gwm-cli)
`config`, `naming`, `worktree`, `bootstrap`, `cli`, `tui`, `tests`, `docs`, `ci`, `structure`, `launcher`, `github`, `doctor`, `skill`, `changelog`. Choisissez le sous-système touché par le diff ; ajoutez-en de nouveaux avec parcimonie.
### helpers commit-prefix
gwm peut produire le préfixe canonique pour vous afin que vous n'ayez pas à taper à la main l'emoji + le type + le scope de l'issue :
```bash
gwm commit-prefix # → :sparkles: feat(#41): (for the current branch)
gwm commit-prefix --unicode # → ✨ feat(#41):
gwm commit-prefix --branch fix/#117-leak
```
Pour un flux entièrement automatique, installez le hook `commit-msg` opt-in — il préfixe le préfixe résolu lorsque votre message ne commence pas déjà par l'un d'eux :
```bash
gwm hooks install commit-msg # refuses to clobber an existing hook
gwm hooks install commit-msg --force # overwrite an existing hook
```
Le hook respecte `core.hooksPath`, résout les fichiers `.git` de worktree liés, et se dégrade gracieusement lorsque `gwm` n'est pas sur le `$PATH` au moment du commit. Les équipes peuvent surcharger des emoji individuels via le bloc `[gitmoji]` dans `.gwm.toml` ; `gwm types --gitmoji` affiche le tableau résolu avec les colonnes unicode + `:shortcode:`.
### changements cassants (breaking changes)
Ajoutez `!` après le type et ajoutez un footer `BREAKING CHANGE:` :
```
✨ feat(config)!: rename [worktree.base] to [worktree.root]
BREAKING CHANGE: rename [worktree.base] to [worktree.root]. Existing
configs continue to parse but emit a one-shot deprecation warning;
the alias will be removed in v1.0.
```
## séparation du CHANGELOG
Le repo utilise une **séparation racine + par-version** :
- [`CHANGELOG.md`](https://github.com/kbrdn1/gwm-cli/blob/main/CHANGELOG.md) à la racine ne contient **que** :
- `## [Unreleased]` — la section en cours à laquelle les nouveaux commits ajoutent (`Added / Changed / Fixed / Docs / Dependencies`)
- `## Past releases` — un index d'une ligne de chaque stable + pré-release, pointant vers `changelogs/<version>.md`
- [`changelogs/<version>.md`](https://github.com/kbrdn1/gwm-cli/tree/main/changelogs) — un fichier par release, avec les notes complètes.
- Les notes de pré-release (`-rc.N`, `-alpha.N`, `-beta.N`) vivent sous `changelogs/pre-releases/<version>.md`.
Lorsque vous publiez une fonctionnalité en milieu de cycle, ajoutez une puce à `[Unreleased]` dans le fichier racine :
```md
## [Unreleased]
### Added
- ✨ **TUI yank** (`y`) — copy the selected worktree's path to the system clipboard. ([#73](https://github.com/kbrdn1/gwm-cli/issues/73))
```
Au moment de la release (réalisée par un commit `🏗️ build: cut vX.Y.Z`), `[Unreleased]` est déplacé dans un nouveau `changelogs/<version>.md` et la section racine est réinitialisée à vide. Le job CI `release.yml` source ses notes de release depuis `changelogs/<version>.md`, jamais depuis le fichier racine — corrigé par le commit `4a76a3d` après qu'une release antérieure ait utilisé une mauvaise source.
## checklist de pull-request
Chaque PR devrait cocher :
- La branche suit `<type>/#<issue>-<description>`
- Les commits suivent Gitmoji + Conventional Commits, atomiques
- Un test échouant a d'abord figé le comportement, puis est passé au vert — voir [Tests → Le TDD est obligatoire](/fr/development/testing#le-tdd-est-obligatoire). Les PRs qui ajoutent ou modifient un comportement sans diff de test associé sont renvoyées.
- `cargo test`, `cargo clippy --all-targets -- -D warnings`, `cargo fmt --check` tous au vert sur la matrice ubuntu / macos / windows
- CHANGELOG.md mis à jour sous `[Unreleased]` (ou N/A pour des refactors purs sans changement observable)
- `gwm doctor` s'exécute proprement sur un worktree neuf de la branche
Le template de PR ([`.github/PULL_REQUEST_TEMPLATE.md`](https://github.com/kbrdn1/gwm-cli/blob/main/.github/PULL_REQUEST_TEMPLATE.md)) porte la version complète.
### stratégie de merge
Les PRs atterrissent comme un **commit de merge classique** — jamais de squash, jamais de suppression de la branche source. L'historique de commits atomiques est l'artefact ; l'écraser perd la trace par-préoccupation que le format Conventional Commits existe pour préserver.
## historique
gwm a commencé comme une réécriture en Rust de `tools/worktree-manager.sh` — un script bash lié à la stack Laravel d'une équipe et à un historique d'incidents (l'incident du `.env`-pointant-vers-AWS-RDS derrière les [Regex guards](/fr/configuration/guards#lhistoire-dorigine)). La version Rust conserve les leçons, les rend configurables par repo, et est livrée comme un binaire unique de sorte qu'elle fonctionne dans chaque repo sans copies de scripts shell par projet.
L'héritage bash est encore visible par endroits — les sigils `✓ / ! / ✗` dans les rapports de bootstrap et de doctor, la normalisation des slugs en kebab-case, les invariants no-symlink sur `vendor/` et `node_modules/` — tous repris du script original. La réécriture Rust a ajouté la TUI, la surface de configurabilité (`.gwm.toml`), la grammaire de prédicats `when:`, le linking GitHub et les launchers configurables.
## en lien
- [Tests](/fr/development/testing) — quoi exécuter avant un push, convention de test-sentinelle
- [Roadmap](/fr/roadmap) — items ouverts que les contributeurs peuvent reprendre
- [`CONTRIBUTING.md`](https://github.com/kbrdn1/gwm-cli/blob/main/CONTRIBUTING.md) — la source de vérité en version longue