Normez vos branches avec validate-branch-name
Par Maxime Bréhin • Publié le 6 septembre 2021
• 4 min
Lorsqu’on utilise un outil de gestion de versions (qui sait gérer les branches), on en vient très vite à se poser la question : comment nommer au mieux mes branches ?
Il n’existe (hélas ?) pas de convention ou de standard comme on peut le voir pour les commits. Cependant il est recommandé de nommer soigneusement vos branches pour identifier facilement le thème global traité par un ensemble de commits. On définit donc généralement une convention.
Comment faire en sorte que cette convention soit respectée ?
Localement, Git ne nous donne pas la possibilité d’intercepter l’ensemble des scénarios de création pour vérifier le nom de la branche. Cependant nous pouvons intercepter l’évènement de “partage” des branches pour garantir qu’on ne crée pas sur le dépôt distant une branche mal nommée (c’est finalement plus utile, car l’intérêt d’un nommage soignée réside surtout dans la collaboration). On peut mettre ça en place avec le hook de pre-push et l’utilitaire validate-branch-name. Et pour que ça marche pour tout le monde sur le projet sans avoir à y penser, on utilise husky, que nous avons détaillé par le passé.
Fonctionnement de validate-branch-name
validate-branch-name analyse la branche que vous tentez de pousser (git push) et stoppe l’opération si les contraintes ne sont pas respectées.
On peut renseigner ces contraintes dans un fichier de configuration. Sinon les motifs autorisés par défaut seront utilisés et vérifieront que :
- les branches correspondent exactement à master ou develop ;
- sinon que les branches sont préfixées par feature, fix, hotfix ou release, suivi d’un slash (
/).
Mise en place
Tout comme husky, il s’agit d’un module npm pour la phase de développement :
# Installation
npm install --save-dev validate-branch-name
# Configuration en pre-push via husky
npx husky add .husky/pre-push "npx --no-install validate-branch-name"Puis on définit selon nos règles la configuration dans le fichier .validate-branch-namerc.js :
module.exports = {
pattern: '^(main|staging|production)$|^(bump|feat|fix|rel(?:ease)?)/.+$',
errorMsg:
'🤨 La branche que tu essaies de pusher ne respecte pas nos conventions, tu peux la renommer avec `git branch -m <nom-actuel> <nouveau-nom>`',
}Plus tard, quand on tentera de partager une branche mal nommée, on se fera rattraper par le col et notre push sera rejeté, nous encourageant à bien nommer notre branche :
Recommandations de convention
À défaut d’un guide en ligne pour une convention bien établie, je vous fais un résumé de ce qui pourrait s’en rapprocher, basé sur mon propre vécu et les retours d’expérience dont on m’a fait part.
Je vous encourage, pour bien définir vos catégories de branches (et donc leur nommage), à vous interroger sur les grands rôles ou thèmes qui seront utiles à votre projet.
Note : vous remarquerez peut-être qu’une partie des recommandations qui suivent sont similaires à des workflows documentés tels que le GitLab flow ou le Git flow. C’est logique si on considère que les noms de nos branches doivent faire écho à notre gestion de projet.
Quels environnements ?
À l’initialisation d’un projet, Git crée par défaut une branche main (anciennement master). Cette branche peut prendre le rôle que nous désirons et peut même être renommée. Elle est le plus souvent utilisée comme tronc commun des développements ou comme branche de production.
Outre cette branche déjà existante à la création du projet, on retrouvera souvent des branches pour les “environnements” suivants :
production: celle qui sert à l’extraction / la génération de nos livrables ;preproduction/staging: permet des vérifier le livrable avant fusion dans la production (assurance qualité) ;develop/main: branche de développement stable (jouera parfois le rôle depreproductionpour limiter la profondeur des branches).
Certains projets ont plusieurs versions de production à un instant T. Leur maintenance nécessitera des branches dédiées : release-X.X.X (pour éviter la confusion avec d’éventuels tags nommés vX.X.X).
Quelles étapes traverse mon projet ?
La plupart des projets de développement passent par des étapes de création, d’amélioration et de correction. On isole ainsi deux grands rôles pour lesquels nous pourrions utiliser des préfixes dans notre convention :
feat/pour la création et l’amélioration des fonctionnalités (en raccourci de feature) ;fix/ouhotfix/pour la gestion des corrections (problèmes liés à la production).
Le suffixe prendrait ensuite une valeur contextuelle, intégrant éventuellement la référence équivalente au thème dans vos outils de gestion de projet (exemple d’une référence d’un ticket ou d’un projet dans GitHub ou GitLab) : fix/24-restore-form-validation.
_Note : je recommande généralement l’usage du slash (/) pour la découpe de contextes / préfixe (un seul niveau suffit généralement, mais on peut imaginer feat/gdpr/notice, par exemple), et réserver les tirets voire soulignés (- ou _) pour les segments du nom, afin de ne pas se limiter à un seul mot (comme dans l’exemple de correctif du paragraphe précédent)._
Cas particuliers de la mise à jour des dépendances
Peut-être utilisez-vous un service comme dependabot qui analyse les dépendances de votre projet et vous propose automatiquement une mise à jour via une branche (et une pull request). Il ne s’agit dans ce cas pas d’une fonctionnalité ni d’un réel correctif. La branche ainsi proposée est alors préfixée bump/. Vous pouvez donc choisir d’employer / d’autoriser ce préfixe dans votre convention.
Envie d’automatiser encore plus ?
On prend vite goût à automatiser au maximum les tâches répétitives ou sources d’erreurs. On gagne en qualité dans nos projets et surtout on gagne du temps pour nous concentrer sur des savoir-faire plus utiles et valables.
Si vous voulez creuser un peu plus le sujet, je vous invite à parcourir nos autres articles sur le même thème :