Conventions git

Quelques conventions pour l'usage de git dans nos projets.

Mode d'emploi plutôt que journal

L'historique doit être aussi clair qu'une documentation pour permettre de rejouer les étapes successives de la construction du logiciel (avec les meilleures pratiques) et donc comprendre sa construction.

Pour y arriver, ne pas hésiter à ré-écrire l'historique (git rebase -i par ex.) avant de pousser sur la branche de fonctionnalité (feature branch).

Des commits atomiques et testés

Le message est préfixé avec la convention : gitmoji.

Un bon commit est un commit court qui ne casse pas les tests. Idéalement il ne diminue pas la couverture de test.

Exemple de rédaction (source)

Summarize changes in around 50 characters or less

More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The
blank line separating the summary from the body is critical (unless
you omit the body entirely); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.

Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.

Further paragraphs come after blank lines.

 - Bullet points are okay, too

 - Typically a hyphen or asterisk is used for the bullet, preceded
   by a single space, with blank lines in between, but conventions
   vary here

If you use an issue tracker, put references to them at the bottom,
like this:

Resolves: #123
See also: #456, #789

Une branche == une fonctionnalité

Pour permettre la re-utilisation de fonctionnalités/code, utiliser des branches au long court semble être une bonne option. Avec Django on doit pouvoir garder une app dans une branche dédié.

Cela permet aussi d'accélérer les tests et améliorer le cloisonnement du code.

Relier les commits au projet

Faire autant de références possibles vers la gestion de projet (GitLab) :

On peut aller même plus loin en utilisant les quick actions qui se déclancheront une fois sur le serveur.

Les branches principales

production ou stable pour le code de production (projet) ou stable (paquet), on ne commit jamais directement dessus : on n'y fait que des fusions (merge), avec titre explicite (pas de Merge branch 'foo'…)

preprod est la branche de qualification (pre-production), seul les corrections rapide (quick-fixes) peuvent y être commité en direct.

Sur ces 2 branches, on ne ré-écrit jamais l'historique

Les branches au long court

Celle que l'on peut retrouver dans divers projets Django :

  • core, le projet Django
  • a14n, l'app de gestion de l'authentification
  • user, l'app de gestion utilisateur
  • documentation, la documentation du projet

Celles spécifique à une fonctionnalité dans un projet - candidate, drover, sipa, …

N'utiliser qu'un nom et si possible court.

Les branches de travail

Elles reprennent le nom de la branche d'où elles ont commencées et ajoutent l'id du ticket correspondant :

  • candidate-46, drover-56, sipa-50, …

Les branches provisoires

Toujours préfixée de wip- et n'ajoutant que l'id du ticket : wip-47, wip-55, … Elle permettent de pousser du code incomplet en court d'écriture. Les tests peuvent donc échouer sur les commits concerné et ne seront pas lancé par l'intégration continue une fois la branche poussée sur le serveur.

On peut en plus préfixer le message de commit : WIP:… notamment pour s'en servir de pense bête et noté où en en était dansle dev.

Les branches d'archive

Lorsque une implémentation différente à été commencée/proposée pour un ticket et que l'on souhaite la conserver pour mémoire on ajoute le sufixe -alt à cette branche. Charge aux commits d'être assez clairs pour l'avenir'.

Étiquettes de version

On ne déploit que des versions ayant un tag correspodant au numéro de version, par exemples : 0.2.7, 1.0.3, 0.0.12-alpha, 0.0.21-rc1, etc…

Quelques options utiles

Ne pas hésiter à les rajouter en alias :

Commandes Action Documentation
git rebase --interactive <hash>^ réécrire l'historique lien
git diff --cached/git diff --staged afficher les changements indexés lien
git add --patch pour choisir ce que l'on indexe lien
git cherry-pick <hash> récupérer un commit et l'appliquer sur HEAD lien
git commit --fixup=<hash> puis git rebase -i --autosquash --autostash <hash>^ fondre un commit dans un précédent
branch -av lister les branches
commit --amend --no-edit ajouté au commit précédent sans changer le message
diff --ignore-all-space --word-diff afficher les changements aux mots (plutôt qu'à la ligne) avec HEAD sans tenir compte des espaces
log --graph --oneline --decorate --since=7days --all les commits de toutes les branches, regroupé et limité aux 7 derniers jours

Votre avis compte!

Ne pas hésiter à proposer des mises à jour pour cette page