Conventional Branch

Conventional Branch 1.1.0

Résumé

Conventional Branch fait référence à une convention de nommage structurée et standardisée pour les branches Git qui vise à rendre les branches plus lisibles et exploitables. Nous avons suggéré quelques préfixes de branches que vous pourriez vouloir utiliser, mais vous pouvez également spécifier votre propre convention de nommage. Une convention de nommage cohérente facilite l’identification des branches par type.

Points clés

1. Noms de branches orientés objectif : Chaque nom de branche indique clairement son objectif, facilitant la compréhension par tous les développeurs de l’objet de la branche.
2. Intégration avec CI/CD : En utilisant des noms de branches cohérents, cela peut aider les systèmes automatisés (comme les pipelines d’intégration continue/déploiement continu) à déclencher des actions spécifiques en fonction du type de branche (par exemple, déploiement automatique depuis les branches de release).
3. Collaboration d’équipe : Cela encourage la collaboration au sein des équipes en rendant explicite l’objectif de la branche, réduisant les malentendus et facilitant le passage d’une tâche à l’autre pour les membres de l’équipe sans confusion.

Spécification

Préfixes de nommage des branches

La spécification des branches prend en charge les préfixes suivants et doit être structurée comme suit :

<type>/<description>

Préfixes d’objectif — décrivent l’intention du travail :

• feature/ (ou feat/) : Pour les nouvelles fonctionnalités (par exemple, feature/add-login-page, feat/add-login-page)
• bugfix/ (ou fix/) : Pour les corrections de bugs (par exemple, bugfix/fix-header-bug, fix/header-bug)
• hotfix/ : Pour les corrections urgentes (par exemple, hotfix/security-patch)
• release/ : Pour les branches préparant une release (par exemple, release/v1.2.0)
• chore/ : Pour les tâches non liées au code comme les dépendances, les mises à jour de documentation (par exemple, chore/update-dependencies)

Préfixes de source d’agent IA — identifient les branches générées par des agents de codage IA :

Les branches principales (main, master, develop) n’utilisent pas de préfixe.

Règles de base

1. Utilisez des caractères alphanumériques en minuscules, des tirets et des points : Utilisez toujours des lettres minuscules (a-z), des chiffres (0-9), et des tirets (-) pour séparer les mots. Évitez les caractères spéciaux, les underscores, ou les espaces. Les points (.) sont autorisés dans toute description, généralement pour les numéros de version (par exemple, release/v1.2.0, chore/upgrade-node-v20.11).
2. Pas de tirets ou points consécutifs, en début ou en fin : Assurez-vous que les tirets et les points n’apparaissent pas de manière consécutive (par exemple, feature/new--login, release/v1.-2.0), ni au début ou à la fin de la description (par exemple, feature/-new-login, release/v1.2.0.).
3. Restez clair et concis : Le nom de la branche doit être descriptif mais concis, indiquant clairement l’objectif du travail.
4. Incluez les numéros de ticket : Le cas échéant, incluez le numéro de ticket de votre outil de gestion de projet pour faciliter le suivi. Par exemple, pour un ticket issue-123, le nom de la branche pourrait être feature/issue-123-new-login.

Grammaire formelle

La grammaire ABNF (Augmented Backus-Naur Form) suivante définit formellement les noms de branches valides :

branch-name     = trunk-branch / prefixed-branch
trunk-branch    = "main" / "master" / "develop"
prefixed-branch = type "/" description
type            = "feature" / "feat" / "bugfix" / "fix"
                / "hotfix" / "release" / "chore"
                / "ai" / "copilot" / "cursor"
                / "claude" / "codex"
description     = desc-segment *("-" desc-segment)
desc-segment    = 1*(ALPHA / DIGIT) *("." 1*(ALPHA / DIGIT))
ALPHA           = %x61-7A   ; lettres minuscules a-z
DIGIT           = %x30-39   ; chiffres 0-9

Remarque : Les tirets ou points consécutifs, ainsi que les tirets ou points en début ou en fin de description, ne sont pas autorisés.

Exemples

Conclusion

• Communication claire : Le nom de la branche seul fournit une compréhension claire de son objectif et du changement de code.
• Compatible avec l’automatisation : S’intègre facilement dans les processus d’automatisation (par exemple, différents workflows pour feature, release, etc.).
• Évolutivité : Fonctionne bien dans les grandes équipes où de nombreux développeurs travaillent simultanément sur différentes tâches.

En résumé, conventional branch est conçu pour améliorer l’organisation du projet, la communication et l’automatisation dans les workflows Git.

Outils

Utilisez ces outils pour adopter et appliquer Conventional Branch dans votre projet :

• commit-check: Vérifiez localement les noms de branches, les messages de commit et les métadonnées Git associées.
• commit-check-action: Validez automatiquement les noms de branches dans GitHub Actions.
• Conventional Branch Skill: Apprend aux assistants de codage IA à créer des noms de branches Conventional Branch valides.

Installez la skill avec :

npx skills add conventional-branch/conventional-branch --skill conventional-branch

FAQ

Qu’est-ce qu’un nom de branche ?

Un nom de branche est l’étiquette que Git donne à une ligne de développement, comme main ou feature/add-login-page ; Git le conserve sous forme de ref dans refs/heads/. Git accepte une grande variété de noms, si bien qu’un nom de branche, à lui seul, ne dit rien de fiable sur le travail qu’elle contient. Conventional Branch lui donne une structure, <type>/<description> : un type qui indique à quoi sert le travail, puis une description courte, en minuscules, dont les mots sont séparés par des tirets. Par exemple :

• feature/add-login-page
• bugfix/fix-header-bug
• release/v1.2.0

Les branches principales (main, master, develop) ne prennent pas de préfixe.

Comment nommer une branche de feature ?

Commencez-la par feature/, ou par l’alias court feat/, et décrivez la fonctionnalité après la barre oblique. Si le travail a un ticket dans votre outil de gestion de projet, incluez son numéro. Par exemple :

• feature/add-login-page
• feat/add-login-page
• feature/issue-123-new-login

Qu’est-ce qu’une branche de chore ?

Une branche chore/ sert aux tâches non liées au code, comme la mise à jour des dépendances ou de la documentation. Les types de branches sont volontairement moins nombreux que les types de Conventional Commits (voir plus bas) ; ce genre de maintenance relève donc de chore/. Par exemple :

• chore/update-dependencies
• chore/upgrade-node-v20.11
• chore/update-generated-files

Certains bots de dépendances, comme Renovate, peuvent aussi être configurés pour utiliser ce préfixe ; voir Bots et automatisation.

Comment nommer une branche de release ?

Utilisez release/ suivi de ce que la branche prépare, généralement le numéro de version. Les points sont autorisés, mais pas au début ni à la fin de la description, ni à côté d’un tiret :

• release/v1.2.0 — valide
• release/v1.2.0. — invalide : point final
• release/v1.-2.0 — invalide : tiret à côté d’un point

Un préfixe cohérent permet aussi à un pipeline d’agir sur release/*, par exemple pour déployer automatiquement depuis les branches de release.

Comment nommer une branche de hotfix ?

Utilisez hotfix/ pour une correction urgente, et bugfix/ (ou fix/) pour une correction qui ne l’est pas. Décrivez ce qui est corrigé, et incluez le numéro de ticket s’il y en a un. Par exemple :

• hotfix/security-patch
• hotfix/issue-123-security-patch
• bugfix/fix-header-bug, pour une correction non urgente

Comment Conventional Branch se rapporte-t-il à Conventional Commits ?

Conventional Branch est inspiré par Conventional Commits et suit une philosophie similaire : apporter une structure lisible par les humains et les machines aux métadonnées Git. Tandis que Conventional Commits standardise les messages de commit, Conventional Branch standardise les noms de branches. Les deux spécifications se complètent naturellement.

Conventional Branch a-t-il inventé ces préfixes ?

Non. Des préfixes comme feature/, hotfix/ et release/ ont été popularisés vers 2010 par l’outil git-flow, et ce sont les valeurs par défaut d’outils comme le modèle de branches de Bitbucket. Conventional Branch s’appuie sur cette pratique au lieu de la remplacer. Ce qu’il apporte, c’est une définition précise que les personnes et les outils peuvent partager : un ensemble fixe de types, une grammaire formelle, une regex de validation publiée dans spec.json et des cas de conformité, afin que chaque validateur accepte exactement les mêmes noms.

Pourquoi les types de branches ne sont-ils pas aussi détaillés que les Conventional Commits (par ex. build, ci, docs, style, refactor) ?

Les branches sont différentes des commits : elles sont temporaires et principalement utilisées jusqu’à leur fusion. Introduire trop de types pour les branches serait inutile et rendrait leur gestion et mémorisation plus difficiles.

Puis-je définir mes propres types de branches au-delà de ceux listés ?

Oui, en tant qu’extension propre à l’équipe. Les types de la grammaire sont ceux que tout outil conforme accepte ; une branche comme unknown/some-task est donc invalide au regard de la spécification elle-même. Une équipe qui a besoin d’autres types (par exemple experiment/) doit les déclarer explicitement dans son validateur (par exemple dans allow_branch_types de commit-check) et les documenter, afin que les membres de l’équipe et les outils automatisés soient alignés. Le dépôt de la spécification lui-même ajoute par exemple dependabot/ à sa configuration commit-check pour les branches ouvertes par Dependabot.

Pourquoi les noms de branches doivent-ils être en minuscules ?

Pour deux raisons. D’abord, Git stocke le plus souvent les références de branches sous forme de fichiers dans .git/refs/heads/, et les systèmes de fichiers par défaut de macOS et de Windows ne distinguent pas la casse : Feature/login et feature/login y correspondent au même chemin, alors que sous Linux ce sont deux branches distinctes. Un dépôt qui autorise les deux peut donc se comporter différemment d’un clone à l’autre. Ensuite, une seule graphie est plus facile à taper, à rechercher et à filtrer : un outil déclenché par release/* n’a pas à prévoir aussi Release/*.

Quelles sont les principales différences entre v1.1.0 et v1.0.0 ?

v1.1.0 ajoute les Préfixes de source d’agent IA comme nouvelle fonctionnalité principale (voir l’entrée FAQ suivante pour savoir pourquoi ils ont été introduits). Il propose également un site web versionné avec un sélecteur de version permettant aux utilisateurs de consulter les spécifications v1.0.0 et v1.1.0. Tous les noms de branches v1.0.0 existants restent totalement valides — aucun changement cassant.

Pourquoi ajouter des préfixes de source d’agent IA ?

Les agents de codage IA (GitHub Copilot, Cursor, Claude Code, OpenAI Codex, etc.) sont de plus en plus utilisés pour générer du code et créer des pull requests. Chaque agent utilise son propre préfixe de branche (par exemple, copilot/, cursor/). En normalisant ces préfixes dans la spécification Conventional Branch, nous permettons :

1. Identification rapide — les réviseurs et les outils peuvent immédiatement reconnaître les PRs générées par IA
2. Validation par les outils — des outils comme commit-check peuvent valider les branches d’agents IA par rapport à la spécification
3. Un standard d’enregistrement — les nouveaux agents IA peuvent adopter un préfixe documenté au lieu d’inventer des motifs ad-hoc

Le préfixe générique ai/ est disponible pour tout agent IA sans préfixe dédié, ou pour les équipes qui préfèrent un identifiant neutre vis-à-vis du fournisseur. C’est la nouvelle fonctionnalité clé publiée dans v1.1.0 — pour un résumé complet des changements entre versions, voir l’entrée FAQ ci-dessus.

Comment gérer les branches à longue durée de vie comme develop ou staging ?

Les branches d’intégration ou d’environnement à longue durée de vie (par ex., develop ou, de façon spécifique au projet, staging, production) sont traitées comme des branches principales et ne nécessitent pas de préfixe. Dans la grammaire formelle ci‑dessus, seules les branches main/master/develop sont normalisées en tant que trunk-branch ; d’autres noms comme staging ou production relèvent d’extensions propres au projet et doivent être documentés et configurés explicitement dans les outils de validation. Elles doivent être nommées de manière cohérente dans tout le projet.

Quels outils peuvent être utilisés pour identifier automatiquement si un membre de l’équipe ne respecte pas cette spécification ?

Vous pouvez utiliser commit-check pour vérifier la spécification des branches ou commit-check-action si vos codes sont hébergés sur GitHub.