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 thématique (feature branch).

Des commits atomiques et testés

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

Un bon commit est :

  • constitué d'un bon message
  • atomique
  • ne casse pas les tests
  • et 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

Les branches

Relier les commits au projet

Faire autant de références possibles vers la gestion de projet de 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 (au long court)

  • production ou stable pour le code ad hoc. On ne commit jamais directement dessus : seulement des fusions (merge)
  • preprod ou devel pour la qualification du code : les corrections rapides (quick-fixes) peuvent y être commit en direct
  • docs pour la documentation si le projet se prête à une séparation de celle-ci

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

Les branches de travail

Préfixée par l'id et suivi du slang du ticket concerné, le plus simple est de les créer depuis GitLab : 2-login-implementation, 5-update-device-settings, 13-enable-disable-wlan-interface, …

Les branches provisoires

Préfixée par wip-, pour pousser du code incomplet/temporaire. Les tests ne seront pas réalisé par l'intégration continue et peuvent donc échouer sur les commits concerné.

On peut en plus préfixer le message de commit : 🚧 WIP: pour indiguer où en était le dev.

Les branches d'archive

Préfixé par old-, pour les branches que l'on souhaite la conserver.

Étiquettes de version

On ne déploit que des versions ayant un tag correspondant 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