EOLE

{{toc}}

h1. Tu balises quand tu commit ?

h2. Objectif

Montrer au monde une ligne de développement cohérente et compréhensible.

Cela se fait en deux temps :

# Identifier les modifications le plus finement possible lors du développement

# Grouper les modifications de façon logique pour la publication

Lors du développement, on va faire des commits le plus souvent possible, cela permet de _voir_ et _agencer_ les évolutions au cours du développement.

Afin de ne pas se surcharger inutilement et donc se décourager à faire des commits souvent, on pourra faire une exception [[GitBonnesPratiques#De-l’écriture-des-ChangeLog|à la bonne écriture des ChangeLogs]] sur ces branches privées dédiées au développement et utiliser l’option *-m* de @git commit@.

En revanche, avant la publication, il faut tout remettre en ordre :

* Regrouper les commits entre eux de façon logique

* Réécrire les [[GitBonnesPratiques#De-l’écriture-des-ChangeLog|ChangeLog]]

h2. N’ayons peur de rien, balisons !

L’écriture de [[GitBonnesPratiques#De-l’écriture-des-ChangeLog|ChangeLog]] sur une seule ligne nous fait perdre de l’information, on se contentera donc du minimum nécessaire afin de s’y retrouver lors de la phase de réécriture des [[GitBonnesPratiques#De-l’écriture-des-ChangeLog|ChangeLog]] :

# Une balise pour cataloguer ce commit

# La raison de la modification du commit

On peut ainsi mettre de côté des commits qui ne font que corriger des typos dans du code qui n’est pas le nôtre, l’idée est :

* Corriger tout ce que l’on voit, si personne d’autre ne l’a déjà fait, alors ça sera fait

* Ne pas se donner du travail supplémentaire à gérer des conflits pour des corrections typographiques et/ou mineures.

h3. Les commits de notre code

Différents types de commit :

* Le commit qui introduit de nouvelles choses (N: New) : quand on est super fort, on ne fait que ce type de commits, mais quand on est super fort, on a pas besoin de git ;-) ;

* Le commit qui corrige un problème fonctionnel dans le nouveau code introduit par le type ci-dessus (F: Fix) : et oui, ça arrive d’oublier des ", ) ou ] ;

* Le commit qui corrige un problème cosmétique (C: Cosmetic) de notre travail, décomposé en 2 sous catégories :

** La correction des messages visibles par l’utilisateur (C: print:) ;

** La correction des commentaires (C: #:).

Voici un exemple type de messages de log court pour une nouvelle fonctionnalité :

<pre>

  moi@work:~/src/bidule(moi/voyant-qui-clignote)$ git log --oneline master..HEAD

  ed002ff N: Ajout de la bibliothèque de gestion du voyant qui clignote

  7610ac6 F: Oublie d’une ) lors de l’appel à ->new()

  c44649d C: #: Mauvaise tournure de phrase: le voyant qui clignote est obligatoire

  2ed9b43 C: print: Typo: 3e personne du pluriel == ent

</pre>

Le balisage de chaque commit permet de facilement s’y retrouver lors de la réorganisation des commits pour [[GitBonnesPratiques#Publication-du-développement|publication]] :

* Les commits № 7610ac6, c44649d et 2ed9b43 doivent être fusionnés avec le commit № ed002ff et leurs messages de commit supprimés

h3. Les commits du code des autres

Il est possible, et vivement recommandé par moi-même, d’introduire une autre série de balises pour tout ce qui est correction en dehors de notre travail en cours.

C’est à dire, la correction des problèmes qui étaient déjà présents avant de faire la nouvelle branche.

* Le commit qui corrige un problème fonctionnel (Fo: Fix other) ;

* Le commit qui corrige un problème cosmétique (Co: Cosmetic other), décomposé en 2 sous catégories :

** La correction des messages visibles par l’utilisateur (Co: print:) ;

** La correction des commentaires (Co: #:).

Il est ainsi aisé de savoir quels commits il faut fusionner et quels commits restent autonommes :

<pre>

  moi@work:~/src/bidule(moi/voyant-qui-clignote)$ git log --oneline master..HEAD

  ed002ff N: Ajout de la bibliothèque de gestion du voyant qui clignote

  7610ac6 F: Oublie d’une ) lors de l’appel à ->new()

  74fe39b Co: #: Erreur de description de la variable "remote" de la méthode Bidule::Truc::Machiner()

  c44649d C: #: Mauvaise tournure de phrase: le voyant qui clignote est obligatoire

  9972b58 Fo: La méthode Bidule::Truc::Biduler() n’étant jamais utilisée, personne n’a vu qu’elle ne fonctionnait pas

  9a6c6c9 Co: print: Typo: Correction du message de l’exception Bidule::Exception::NoBattery

  2ed9b43 C: print: Typo: 3e personne du pluriel == ent

</pre>

Dans le log précédent :

# On groupera les commits @ed002ff@, @7610ac6@, @c44649d@ et @2ed9b43@ au début en les fusionnant et supprimant leur message de log (« @squash@ »)

# On groupera les commits @74fe39b@, @9972b58@ et @9a6c6c9@ comme étant les plus récents sur la branches.

On peut ainsi :

# Dans un premier temps, faire un merge de la première moitié de l’historique de cette branche dans la branche de publication pour publier notre travail.

# Dans un second temps, faire un merge du reste de cette branche dans la branche de publication pour publier les autres modifications

h2. Comment s’en servir ?

Lors d’un @git rebase -i HEAD~7@, l’éditeur est lancé avec le contenu suivant :

<pre>

  moi@work:~/src/bidule(moi/voyant-qui-clignote)$ git rebase -i HEAD~7

  pick ed002ff N: Ajout de la bibliothèque de gestion du voyant qui clignote

  pick 7610ac6 F: Oublie d’une ) lors de l’appel à ->new()

  pick 74fe39b Co: #: Erreur de description de la variable "remote" de la méthode Bidule::Truc::Machiner()

  pick c44649d C: #: Mauvaise tournure de phrase: le voyant qui clignote est obligatoire

  pick 9972b58 Fo: La méthode Bidule::Truc::Biduler() n’étant jamais utilisée, personne n’a vu qu’elle ne fonctionnait pas

  pick 9a6c6c9 Co: print: Typo: Correction du message de l’exception Bidule::Exception::NoBattery

  pick 2ed9b43 C: print: Typo: 3e personne du pluriel == ent

  # Rebase ed002ff..2ed9b43 onto ed002ff

  #

  # Commands:

  #  p, pick = use commit

  #  r, reword = use commit, but edit the commit message

  #  e, edit = use commit, but stop for amending

  #  s, squash = use commit, but meld into previous commit

  #  f, fixup = like "squash", but discard this commit's log message

  #  x, exec = run command (the rest of the line) using shell

  #

  # If you remove a line here THAT COMMIT WILL BE LOST.

  # However, if you remove everything, the rebase will be aborted.

  #

</pre>

Il est ainsi possible de *fusionner* les 4 commits qui nous concernent en un seul en déplaçant les lignes et en leur appliquant la commande de "fixup" :

<pre>

  moi@work:~/src/bidule(moi/voyant-qui-clignote)$ git rebase -i HEAD~7

  pick ed002ff N: Ajout de la bibliothèque de gestion du voyant qui clignote

  f 7610ac6 F: Oublie d’une ) lors de l’appel à ->new()

  f c44649d C: #: Mauvaise tournure de phrase: le voyant qui clignote est obligatoire

  f 2ed9b43 C: print: Typo: 3e personne du pluriel == ent

  pick 74fe39b Co: #: Erreur de description de la variable "remote" de la méthode Bidule::Truc::Machiner()

  pick 9972b58 Fo: La méthode Bidule::Truc::Biduler() n’étant jamais utilisée, personne n’a vu qu’elle ne fonctionnait pas

  pick 9a6c6c9 Co: print: Typo: Correction du message de l’exception Bidule::Exception::NoBattery

  # Rebase ed002ff..2ed9b43 onto ed002ff

  #

  # Commands:

  #  p, pick = use commit

  #  r, reword = use commit, but edit the commit message

  #  e, edit = use commit, but stop for amending

  #  s, squash = use commit, but meld into previous commit

  #  f, fixup = like "squash", but discard this commit's log message

  #  x, exec = run command (the rest of the line) using shell

  #

  # If you remove a line here THAT COMMIT WILL BE LOST.

  # However, if you remove everything, the rebase will be aborted.

  #

</pre>

Une fois la mise au propre de notre historique faite, nous souhaitons publier ces modifications.

Nous allons donc rebaser notre travail sur la branche @origin/master@ :

# On commence par télécharger les éventuels modifications :

<pre>

  moi@work:~/src/bidule(moi/voyant-qui-clignote)$ git fetch origin

  remote: Counting objects: 24, done.

  remote: Compressing objects: 100% (15/15), done.

  remote: Total 15 (delta 12), reused 0 (delta 0)

  Unpacking objects: 100% (15/15), done.

  From git://far-far.away.example.net/bidule.git

     7ced305..9171f31  master     -> origin/master

</pre>

# On rebase en modifiant les messages de commit afin de supprimer le balisage, il n’y a rien à fusionner :

<pre>

  moi@work:~/src/bidule(moi/voyant-qui-clignote)$ git rebase origin/master

  r ed002ff N: Ajout de la bibliothèque de gestion du voyant qui clignote

  r 74fe39b Co: #: Erreur de description de la variable "remote" de la méthode Bidule::Truc::Machiner()

  r 9972b58 Fo: La méthode Bidule::Truc::Biduler() n’étant jamais utilisée, personne n’a vu qu’elle ne fonctionnait pas

  r 9a6c6c9 Co: print: Typo: Correction du message de l’exception Bidule::Exception::NoBattery

  # Rebase ed002ff..9a6c6c9 onto 9171f31

  #

  # Commands:

  #  p, pick = use commit

  #  r, reword = use commit, but edit the commit message

  #  e, edit = use commit, but stop for amending

  #  s, squash = use commit, but meld into previous commit

  #  f, fixup = like "squash", but discard this commit's log message

  #  x, exec = run command (the rest of the line) using shell

  #

  # If you remove a line here THAT COMMIT WILL BE LOST.

  # However, if you remove everything, the rebase will be aborted.

  #

</pre>

Si un conflit est détecté sur le commit *9a6c6c9 Co: print: Typo: Correction du message de l’exception Bidule::Exception::NoBattery*,

il suffira d’annuler le rebase avec @git rebase --abort@ et de le recommencer, cette fois ci en supprimant la ligne correspondante.