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

Via pull/merge request (workflow standard)

La méthode la plus courante sur GitHub/GitLab :

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

1. Vérifier l’état du projet

# 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

# 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 dernier tag :

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

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

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

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

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 dernier tag
• Keep a Changelog + Conventional Commits structurent la documentation des changements
• Automatisez autant que possible : changelog, release notes, CI

Prochaines étapes

Tags et versions SemVer et gestion des tags en détail.

Workflows Git Gitflow, Trunk-Based : choisissez votre stratégie.

Réécrire l'historique Nettoyez avant de publier avec rebase -i.

×

📖 Voir la documentation →