Maintenir un projet Git

Maintenir un projet Git implique d'accepter les contributions, de préparer les releases et de garder un historique exploitable. Que vous gériez un projet open source ou un dépôt d'équipe interne, ce guide couvre les outils et pratiques du mainteneur.

Prérequis : Pull requests et code review et Tags et versions.

Ce que vous allez apprendre

• Accepter des contributions externes avec le workflow fork + PR
• Préparer et tagger une release selon la convention SemVer
• Générer un changelog à partir de l'historique Git
• Maintenir les branches de maintenance pour les correctifs sur versions stables

Accepter des contributions

Un contributeur externe n'a pas le droit d'écrire dans votre dépôt : il travaille sur une copie et vous propose ses commits. Deux mécanismes existent pour les intégrer, et ils diffèrent surtout par ce qu'ils exigent de l'infrastructure. La pull request suppose une plateforme web qui héberge la discussion et la CI ; les patches par email ne demandent rien d'autre que Git et une boîte aux lettres. Dans les deux cas, c'est vous qui créez le commit final dans votre historique.

Via pull/merge request (workflow standard)

C'est la méthode par défaut sur GitHub et GitLab. Le point à décider avant le premier merge est la stratégie d'intégration : elle détermine l'allure de votre historique et ne se change pas facilement après coup.

1. Le contributeur ouvre une PR/MR

2. Vous reviewez le code (voir le guide PR)

3. Vous demandez des corrections si nécessaire

4. Quand le code est prêt, vous mergez avec la stratégie choisie (merge commit, squash, ou rebase)

5. Vous supprimez la branche source

Via patches (workflow email/legacy)

Certains projets (comme le noyau Linux) utilisent encore les patches par email. Git fournit deux commandes pour ce workflow.

Côté contributeur, générer les patches :

# Créer un fichier .patch par commit (depuis main)
git format-patch main

Résultat : des fichiers comme 0001-Ajouter-la-validation.patch, 0002-Corriger-le-timeout.patch.

Chaque fichier contient le diff, le message de commit, l'auteur et la date. Le contributeur envoie ces fichiers par email ou les joint à un ticket.

Côté mainteneur, appliquer les patches :

# Appliquer un patch (crée un commit avec l'auteur original)
git am 0001-Ajouter-la-validation.patch

# Appliquer tous les patches d'un dossier
git am patches/*.patch

git am (apply mailbox) conserve l'auteur, la date et le message originaux.

Vérifier avant d'appliquer

Pour vérifier qu'un patch s'applique proprement sans le commiter :

git apply --check 0001-Ajouter-la-validation.patch

Si un conflit survient pendant git am :

# Résoudre le conflit dans le fichier
git add fichier-en-conflit.txt
git am --continue

# Ou abandonner
git am --abort

Préparer une release

Une release est une photo datée de votre projet à laquelle vos utilisateurs vont se référer pendant des mois. Les quatre étapes ci-dessous se font dans cet ordre pour une raison précise : le tag doit être posé sur un commit qui contient déjà le changelog à jour, sinon la version publiée ne documente pas ses propres changements. Contrairement à une branche, un tag poussé est destiné à ne plus bouger, le déplacer casse les clones et les caches de vos utilisateurs.

1. Vérifier l'état du projet

Ces deux commandes répondent à la question « ai-je oublié quelque chose » : la première liste les branches jamais intégrées, la seconde tout ce qui est entré depuis la version précédente.

# Branches non mergées
git branch --no-merged main

# Derniers commits depuis la dernière release
git log v1.2.0..HEAD --oneline

2. Mettre à jour le changelog

Le changelog documente les changements visibles pour les utilisateurs. Format recommandé (Keep a Changelog) :

## [1.3.0] - 2026-03-28

### Added
- Composant Avatar avec upload d'image (#42)
- Support du mode sombre (#38)

### Fixed
- Redirect après déconnexion (#45)
- Timeout API sur les grandes requêtes (#41)

### Changed
- Mise à jour de la dépendance auth-lib vers 3.x

3. Taguer la release

-a crée un tag annoté, un vrai objet Git horodaté et attribué à son auteur, seul type reconnu par git describe sans option. git push ne pousse aucun tag par défaut, il faut le nommer explicitement.

# Tag annoté avec message
git tag -a v1.3.0 -m "Release 1.3.0 : avatar, mode sombre, corrections"

# Pousser le tag
git push origin v1.3.0

4. git describe : identifier une version

git describe génère un nom de version lisible basé sur le tag annoté le plus récent atteignable ; utilisez --tags pour inclure aussi les tags légers :

git describe

v1.3.0-5-g2a1b3c4

Décodage : 5 commits après le tag v1.3.0, sur le commit 2a1b3c4.

Options utiles :

# Inclure les tags légers
git describe --tags

# Toujours afficher le hash long
git describe --long

git describe est utile dans les scripts de build pour identifier la version exacte d'un binaire.

Générer un changelog automatique

Rédiger le changelog à la main coûte du temps à chaque release et finit par être bâclé. L'automatiser est possible, à une condition : que vos messages de commit soient structurés, puisqu'ils deviennent la source de données. C'est un choix qui engage l'équipe en amont, aucun outil ne peut deviner rétroactivement qu'un commit intitulé « fix » corrigeait un bug visible par l'utilisateur.

Depuis les commits

Si vos messages de commit suivent une convention (Conventional Commits), des outils peuvent générer le changelog automatiquement :

# Commits depuis le dernier tag, groupés par type
git log v1.2.0..HEAD --oneline | grep -E '^[a-f0-9]+ (feat|fix|docs|chore)'

Outils dédiés

Le choix se fait moins sur les fonctionnalités, très proches, que sur ce qui est déjà installé chez vous et sur la convention que l'outil impose. changie se distingue en n'analysant pas l'historique : les entrées sont écrites à la main dans des fichiers YAML, ce qui convient aux équipes qui refusent de contraindre leurs messages de commit.

Outil	Langage	Convention requise
conventional-changelog	Node.js	Conventional Commits
git-cliff	Rust	Configurable
changie	Go	YAML fragments
release-please	GitHub Action	Conventional Commits

Glissez pour voir

Conventional Commits

La convention Conventional Commits structure les messages comme type(scope): description. Les types courants : feat, fix, docs, chore, refactor, test, ci. Cette convention permet d'automatiser le versioning et le changelog.

Notes de release (GitHub/GitLab)

Les plateformes permettent de créer des notes de release associées à un tag :

• GitHub : Releases → Draft a new release → sélectionner le tag → rédiger les notes (ou « Generate release notes » automatique)
• GitLab : Deployments → Releases → New release

Les notes de release incluent généralement :

• Un résumé des changements (depuis le changelog)
• Les contributeurs
• Les liens vers les issues/PR fermées
• Les instructions de migration si breaking changes

Bonnes pratiques du mainteneur

La partie difficile de la maintenance n'est pas technique : c'est la prévisibilité. Un contributeur qui ignore quand on lui répondra, sous quel format soumettre, ou quelles règles s'appliquent finit par abandonner sa contribution. Les six points ci-dessous visent tous à rendre le projet lisible de l'extérieur, ce qui réduit d'autant le travail de tri à votre charge.

1. Répondez rapidement aux PR/issues (même si c'est « je regarde cette semaine »)
2. Documentez les conventions : CONTRIBUTING.md, templates de PR/issue
3. Taguez les issues : good first issue, help wanted, bug, enhancement
4. Versionnez sémantiquement : SemVer
5. Automatisez : CI/CD, linting, changelog, release notes
6. Communiquez les breaking changes clairement dans le changelog et les notes de release

Gérer les PR abandonnées

Une PR abandonnée est une PR ouverte depuis plusieurs semaines sans activité de la part du contributeur. Voici comment la traiter :

1. Évaluez la valeur : le changement est-il encore pertinent ?

2. Relancez une seule fois avec un message clair :

   Bonjour @contributeur, ce changement nous intéresse toujours.
   Pourriez-vous résoudre les conflits et mettre à jour la branche ?
   Nous clôturerons cette PR sous 2 semaines sans réponse.

3. Si pas de réponse : fermez la PR avec un message bienveillant en précisant qu'elle peut être rouverte ou recréée :

   Clôture faute d'activité. Le changement reste bienvenu, n'hésitez
   pas à recréer une PR depuis une branche à jour.

4. Si le changement est utile, vous pouvez vous-même reprendre le travail sur une nouvelle branche en créditant l'auteur original dans le message de commit :

   git commit -m "feat: ajouter X
   
   Co-authored-by: Prénom Nom <email@example.com>"

Communiquer les breaking changes

Un breaking change est une modification qui casse la compatibilité avec les utilisateurs existants (changement d'API, suppression d'une option, changement de comportement par défaut).

Dans le changelog

Marquez les breaking changes explicitement dans le changelog :

## [2.0.0] - 2026-04-01

### BREAKING CHANGES
- Suppression de l'option `--legacy-mode` (remplacée par `--compat v1`)
- L'option `--output` accepte maintenant un chemin absolu uniquement

### Migration depuis 1.x
Remplacez `--legacy-mode` par `--compat v1` dans vos scripts.

Dans les notes de release et le tag

Préfixez le message du tag annoté avec une mention explicite :

git tag -a v2.0.0 -m "BREAKING: suppression --legacy-mode. Voir CHANGELOG pour la migration."
git push origin v2.0.0

Avec SemVer

Un breaking change justifie un incrément majeur (1.x.y → 2.0.0). Ne jamais introduire un breaking change dans un patch ou un mineur. Voir Tags et versions.

Dépannage : problèmes courants

Les quatre situations ci-dessous reviennent régulièrement chez les mainteneurs. Deux d'entre elles méritent une précaution particulière : retaguer une release suppose de supprimer le tag aussi côté distant (git push origin :v1.3.0), et cela ne rattrape pas les clones déjà faits. Les autres se corrigent sans conséquence visible pour les utilisateurs.

Symptôme	Cause probable	Solution
git am échoue avec un conflit	Patch basé sur un autre commit	git am --3way pour un merge 3-way
git describe retourne une erreur	Aucun tag dans l'historique	Créez un tag initial v0.0.1
Changelog incohérent	Messages de commit non structurés	Adoptez Conventional Commits + commitlint
Release taguée sur le mauvais commit	Tag posé trop tôt/tard	git tag -d v1.3.0 puis retaguer

Glissez pour voir

À retenir

• PR/MR : le workflow standard pour accepter les contributions
• git format-patch + git am : le workflow patches pour les projets sans plateforme web
• git tag -a crée un tag annoté pour marquer une release
• git describe génère un identifiant de version basé sur le tag annoté le plus récent atteignable (ajoutez --tags pour inclure les tags légers)
• Keep a Changelog + Conventional Commits structurent la documentation des changements
• Automatisez autant que possible : changelog, release notes, CI

Pour aller plus loin

• Protocoles Git : HTTP, SSH et Git : Les transports disponibles pour exposer le dépôt du projet aux contributeurs.
• Plateformes Git : GitHub, GitLab, Gitea et alternatives : Le comparatif des forges qui outillent la revue et la publication des releases.
• Réécrire l'historique Git : Le nettoyage des contributions avant intégration, avec rebase interactif et filter-repo.

×

📖 Voir la documentation →