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
- branches thématique pour:
- pour les tickets (issues) du projet
- branches au long court pour:
- celles structurant le projet:
docs
,production
,stable
,devel
, … - le code réutilisable, les applications Django par ex.
Relier les commits au projet
Faire autant de références possibles vers la gestion de projet de GitLab:
- vers les tickets
- vers les autres objets GitLab en utilisant le caractère de raccourci adéquat
- fermer automatiquement un ticket
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
oustable
pour le code ad hoc. On ne commit jamais directement dessus : seulement des fusions (merge)preprod
oudevel
pour la qualification du code : les corrections rapides (quick-fixes) peuvent y être commit en directdocs
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…
- suivre la gestion sémantique de version
- pas de préfixe
- suffixe pour les versions alpha, release candidate, 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