EOLE

{{toc}}

L'ancienne page GitBonnesPratiques est ici http://dev-eole.ac-dijon.fr/projects/eole/wiki/RecueilGit

h1. Les bonnes pratiques c’est quoi ?

Ce document n’est pas une référence git, nous n’allons pas réécrire le

"Pro Git book":http://git-scm.org/book/fr, ni les autres références disponibles sur Internet.

Il existe même des "tutoriels":http://gitimmersion.fr/index.html pas à pas bien fait.

Nous allons partir du principe qu’un minimum de connaissance de l’outil git est acquis, notamment 

le "démarrage rapide":http://git-scm.org/book/fr/ch1-0.html et les "bases de git":http://git-scm.org/book/fr/ch2-0.html du livre "Pro Git book":http://git-scm.org/book/fr.

Nous allons essayer de décrire ici une méthodologie de travail basée sur le

système de gestion de version décentralisé "git":https://fr.wikipedia.org/wiki/Git avec les objectifs suivants :

* Communiquer entre développeur

* S’y retrouver dans ses développements, ou comment gérer des ajouts fonctionnels et des corrections de bug en parallèle

* Publier des modifications clairement identifiables et analysables, par des humains et des outils de tests automatiques

Ce document ne représente en rien _LA_ bonne méthode de travail, il s’agit juste d’une façon de faire,

appuyée par l’expérience d’autres personnes que l’on trouve un peu partout sur Internet.

Il est tout à fait possible de trouver autant, voir plus, de références prônant un point de vue opposé ou orthogonal au mien.

h1. De la méthode agile

Comme il est défini dans le "manifeste agile":https://fr.wikipedia.org/wiki/Manifeste_agile#Les_4_valeurs, la première valeur est

« Les individus et leurs interactions ».

Afin de travailler correctement en équipe, il faut communiquer, et

l’outil de gestion de version "git":https://fr.wikipedia.org/wiki/Git, utilisé à EOLE, peut-être un excellent

outil de communication.

h1. De l’écriture des "ChangeLog":https://fr.wikipedia.org/wiki/ChangeLog

Afin de communiquer avec les autres membres d’une équipe sur le travail que chacun effectue, l’écriture d’un ChangeLog, ou plus précisément d’un « commit message » dans la littérature anglaise (qui pourrait être traduit par « message de consignation ») se doit d’être fait correctement(sic).

Que penser d’un message comme « "typo":http://dev-eole.ac-dijon.fr/projects/eole-sso/repository/revisions/f2e5c52482c896b84e57333ba61654286b856f02 » ou encore « "correction d'une coquille":http://dev-eole.ac-dijon.fr/projects/cdc/repository/revisions/0dc6d59ca9c5294790ae1ebe0b035d8a3296ed22 » ?

Un message de commit *doit* expliquer le *pourquoi* de la modification afin de comprendre *ce qui a motivé* le changement.

Le changement en lui même est expliqué par le @diff@.

Nous pouvons établir une règle simple et souple, par exemple :

Un message de commit comprend :

* Une première ligne résumant le *pourquoi* du patch ;

* Une ligne vide pour séparer le sujet ;

* Une description longue optionnelle permettant d’expliciter le

  contexte du résumé donné en première ligne ;

* Une liste de fichier et leur modification.

Une ligne vide sépare les différentes parties : la première est

obligatoire et la troisième est optionnelle pour les changements triviaux

Par exemple :

<pre>

  Le répertoire /usr/share/eole/noyau/ est nécessaire (Fixes: #2405).

  * debian/dirs: Création du répertoire.

</pre>

<pre>

  Simplification de la gestion des noyaux (ref: #2406).

  * creole/fonctionseole.py: Suppression du code effectué par

    eole-kernel-version depuis sa version 2.3-eole37~2.

    Renommage de la variable 'boot_ok' en 'need_boot'.

</pre>

Cela impose les règles suivantes :

# « Ne jamais utiliser l’option "-m" de la commande "git commit" »

# « Ne pas décrire ce que fait le commit mais pourquoi »

La description de se que fait un commit est le rôle du "diff":https://fr.wikipedia.org/wiki/Diff.

Ainsi, le second exemple donné plus haut n’est pas correct : « la première ligne ne décrit pas pourquoi on simplifie la gestion des noyaux ».

h1. De la cohérence de l’histoire du monde

Un système de gestion de version permet avant tout de conserver un

livre d’histoire d’un projet.

Dans les premiers systèmes de gestion de version, cette histoire était

centralisée. Il fallait avoir le droit d’écrire dans le « livre des

comptes et légendes » afin d’y ajouter un morceau, impossible donc de

réécrire l’histoire sans être tout puissant sur le registre.

Grâce aux systèmes décentralisés comme "git":https://fr.wikipedia.org/wiki/Git, tout le monde peut avoir

une copie privée de l’histoire publique d’un projet, pour cela il

suffit de « cloner » l’histoire originale :

<pre>

  moi@work:~/src$ git clone git://far-far.away.example.net/bidule.git

</pre>

À partir de là il est possible de vouloir y ajouter ses propres

morceaux, et cela sans rien demander à personne.

On modifie le projet et on consigne les nouveaux événements dans

notre copie locale de l’histoire du projet :

<pre>

  moi@work:~/src/bidule(master)$ $EDITOR src/bidule.c # On modifie un fichier du projet

  moi@work:~/src/bidule(master)$ git add src/bidule.c # On ajoute un événement à enregistrer dans le livre d’histoire

  moi@work:~/src/bidule(master)$ git commit # On consigne ce nouvel événement

</pre>

Mais l’histoire, c’est un sujet sensible. On ne badine pas avec

l’histoire et on ne la réécrit sous aucun prétexte.

Peu importe si la vérité est ailleurs, l’important c’est que tout le

monde soit d’accord sur la même version des faits.

Si un plaisantin modifie l’histoire et la publie à tout vent, il y

aura conflit.

Nous allons donc édicter la règle suivante :

« On ne réécrit pas l’histoire connue »

Cela sous entend donc que nous pouvons réécrire comme il nous plaît

toute l’histoire qui nous est privée, c’est à dire inconnue de tous

les autres.

Mais dès qu’un événement est rendu public, ce n'est plus possible.

h1. Trop de pull, c’est trop chaud !

Que se passe-t-il si un jour nous souhaitons apprendre les nouvelles

histoires de par le monde ?

Que ce passe-t-il si un jour nous souhaitons partager nos petites

histoires avec le reste du monde ?

La plupart du temps, la réponse donnée à ces questions commence par

quelque chose comme « fais-toi donc un pull ».

Cela se traduit, en terme git, par :

<pre>

  moi@work:~/src/bidule(master)$ git pull

</pre>

Cela est strictement équivalent aux deux commandes suivantes :

<pre>

  moi@work:~/src/bidule(master)$ git fetch origin

  moi@work:~/src/bidule(master)$ git merge origin/master

</pre>

Mais il existe quelques soucis avec cette méthode, la première étant

« qu’une histoire entre en conflit avec l’une des vôtres ».

Un autre problème est que cette méthode « mélange » littéralement

l’histoire publique avec vos histoires privées, même s’il n’y a pas de

conflit, il peut-être difficile de savoir si le résultat aura un sens

ou non.

Dans git, chaque commit a une généalogie, le parent du commit que je

m’apprête à faire est le dernier commit enregistré dans le dépôt.

Lors d’un pull sur un dépôt contenant des modifications, git créé un

commit ayant deux parents dont le seul but est de mélanger la généalogie.

Il est donc préférable d’utiliser la méthode décomposée en deux commandes.

Cela permet de vérifier au préalable si des changements

sont à intégrer, et lesquels, avec les commandes suivantes :

* ChangeLog des différences

<pre>

  moi@work:~/src/bidule(master)$ git log master..origin/master

</pre>

* Liste des fichiers modifiés

<pre>

  moi@work:~/src/bidule(master)$ git diff --stat master..origin/master

</pre>

* Modification du code

<pre>

  moi@work:~/src/bidule(master)$ git diff master..origin/master

</pre>

Mais cela n’empêche nullement :

* D’être potentiellement désastreux : chaque « fusion » (merge) et

  « consignation » de « fusion » (merge commit) sont à la charge de

  chaque développeur ;

* Votre histoire devient illisible. Elle intègre tout un tas de

  « fusion » inexplicables ;

* Retrouver à quel moment précis et quel modification a entraîné un

  changement de comportement devient impossible du fait des

  « fusions »

Tout mélanger dans la même branche, qui devient alors un tronc, pose

des soucis quant à la lecture de l’histoire du projet.

h1. Pour s’y retrouver, il faut s’accrocher aux branches

Une branche est une ligne d’histoire divergente d’un projet, leur

utilisation dans git est très simple et légère.

La création d’une branche peut se faire de deux façons :

# Créer une branche que j’utiliserais plus tard :

<pre>

  moi@work:~/src/projet(master)$ git branch mabranche

  moi@work:~/src/projet(master)$ # on commit dans la branche « master »

</pre>

# Créer une branche et commencer à travailler dedans :

<pre>

  moi@work:~/src/projet(master)$ git checkout -b mabranche

  moi@work:~/src/projet(mabranche)$ # on commit dans la branche « mabranche »

</pre>

Chacune de ces commandes permet de définir, en dernier argument, le point de départ de la nouvelle branche.

Par défaut ce point de départ est le dernier commit de la branche courante.

Tout les commit effectués sur cette branche sont localisés à cette branche.

Cela permet de se focaliser sur une activité :

* Sans risquer d’impacter la vision que les autres ont de l’histoire ;

* Sans se soucier de ce qui peut arriver sur les autres branches ;

* Sans fusionner les modifications de la branche principale dans la

  branche courante.

Il faut travailler ensuite à intégrer cette nouvelle histoire à la ligne principale.

h2. Les voies du temps sont interpénétrables

C’est le principe utilisé par le pull, ce qui est nommé dans la littérature le « merge workflow ».

Ce qui est fait lors d’un @git pull@ entre une branche locale et une branche sur un dépôt distant,

« remote » en jargon git, est applicable entre deux branches d’un dépôt local.

En pratique, on se positionne sur la branche qui doit intégrer les modifications d’une autre,

par exemple une branche publique, et on fusionne la branche privée de développement dans cette branche publique :

<pre>

  moi@work:~/src/projet(master)$ git merge mabranche

</pre>

Pour ensuite publier ces modifications par @git push@.

Ceci induit les mêmes inconvénients que l’utilisation des pull.

Lorsque l’on passe du temps à travailler sur une branche privée, il est tentant de « fusionner » régulièrement une branche publique de référence, afin de se mettre à jour.

Mais cette pratique ne fait que rendre illisible l’histoire privée de cette branche.

Cela rend très difficile la relecture de chaque modification apportée par cette branche car son histoire n’est plus simplement une suite logique d’étapes afin d’arriver à un résultat voulu.

Fusionner des branches amont ("upstream":http://fr.wiktionary.org/wiki/upstream) dans votre branche de travail en cours sans une raison réellement valable est considéré comme une très mauvaise pratique.

Un telle fusion dans une direction erronée (upstream=>branche privée) ne devrait être fait qu’en cas d’absolue nécessitée, par exemple, lorsque votre travail en cours nécessite des nouveautés effectuées sur la branche upstream.

Autrement, votre branche de travail ne sera plus sur un sujet particulier mais deviendra un amas informe de commit de sources diverses et avariées, venant de votre propre branche mais aussi d’upstream contenant du travail fait par d’autres sur des sujets tout aussi divers et variés.

h2. On ne construit que sur les épaules de géants

Il existe une autre approche à la problématique généalogique des

commits, nommé dans la littérature « rebase workflow ».

Ce principe utilise la réécriture de l’historique, par conséquent,

elle ne peut être utilisée que sur des commits non publiés.

Le principe est le même que le greffage en botanique :

# On coupe la branche ;

# On la greffe sur une autre.

En pratique, c’est surtout utilisé pour préparer l’intégration de nos

modifications dans une branche publique.

C’est un peu le miroir du « merge workflow ».

Dans le « merge workflow », la fusion se fait sur la branche publique

et les conflits sont gérés dans l’histoire de la branche publique.

Dans le « rebase workflow », c’est l’inverse, tout se fait dans la

branche que l’on souhaite intégrer à la branche publique.

La procédure est décomposée comme suit :

# Mise de côté de tous les commits de la branche depuis sa création :

  on revient dans le tronc de développement (branche privée) à la

  version sur laquelle notre branche est basée ;

# Intégration de tous les changements de la branche publique survenus

  depuis ;

# Application de tous les commits mis de côté, il faut gérer les

  éventuels conflits.

Avant la procédure, la branche privée était basée sur la branche

publique à un certain instant dans le passé.

Après la procédure, la branche privée est basée sur le dernier commit

de la branche publique.

On a donc changé la base de la branche, d’où le nom de cette méthode.

Tout cela se fait simplement par :

<pre>

  moi@work:~/src/projet(mabranche)$ git rebase master

</pre>

Il est possible de faire fréquemment des rebases des branches privées

par rapport à la branche publique où seront intégrées les

modifications.

On minimise ainsi les conflits ou, plus précisément, on les dilue dans

le temps.

Ce principe de rebase est à utiliser, au moins avant l’intégration à

la branche publique, afin d'avoir une histoire plus propre de la

branche et ce en fusionnant certains commits.

Dans ce cas on ne rebase pas par rapport à une branche publique, mais

par rapport à un commit de la branche privée.

Par exemple, ne pas avoir un commit ajoutant une fonctionnalité et les

30 suivants qui corrigent les inévitables erreurs typographiques.

h1. « Le blabla c’est bien, mais en pratique ? » par moi©®™

h2. Puisque je vous dis que les branches ça ne coûte rien !

Dans git, une branche est simplement un fichier dans l’arborescence du

répertoire @.git/refs/heads/@.

Ce fichier contient l’identifiant du dernier commit de cette branche,

c’est le "SHA1":http://fr.wikipedia.org/wiki/SHA1 du contenu de l’objet (les détails sont accessibles dans

"Les tripes de Git":http://git-scm.org/book/fr/ch9-0.html).

L’identifiant de commit référence un fichier dans l’arborescence du

répertoire @.git/objects/@, avec :

* les deux premiers caractères (1 octet noté en hexadécimal) sont le

  nom d’un sous répertoire ;

* le reste des caractères sont le nom du fichier.

Connaître l’identifiant du dernier commit est suffisant pour remonter

l’arbre généalogique.

Faire une nouvelle branche se résume donc à créer un fichier ne

contenant qu’un identifiant.

On créé une branche dédiée pour le développement à faire :

<pre>

  moi@work:~/src/projet(master)$ git checkout -b issue/42 master

</pre>

h2. Le clonage déontologiquement correcte

Afin de tester nos modifications avant publication, nous pouvons

copier les fichiers sur une machine de test, par quelque moyen que ce

soit.

Un de ces moyens, et le plus simple dans notre cas, est d’utiliser

git.

Étant donné que :

* Nous souhaitons tester les modifications apportées par le

  développement enregistré dans une branche non publiée ;

* Nous ne souhaitons pas publier cette branche privée tant que tout ne

  sera pas propre ;

Nous allons créer une copie conforme de notre dépôt, sur la machine de test.

Le fonctionnement est simple, un dépôt git, qu’il soit sur un serveur

http ou dans notre répertoire, peut servir de base à un clone.

Et un clone, ça peut se faire par "SSH":http://fr.wikipedia.org/wiki/SSH.

Nous avons besoin :

* D’une machine de test ;

* D’un accès "SSH":http://fr.wikipedia.org/wiki/SSH sur cette machine ;

* De l’outil git installé sur cette machine.

Aucun fichier ne sera éditer sur cette machine, cela évite de

s’éparpiller.

Nous mettrons à jour ce dépôt par des pull, ce qui ne posera aucun

soucis comme expliqué plus haut du fait qu’il n’y aura aucune

modification locale à la machine de test.

<pre>

  moi@work:~/src/projet(master)$ ssh user@test-machine

  user@test-machine:~$ git clone ssh://moi@work/home/moi/src/projet && cd projet

  user@test-machine:~/projet(master)$ git checkout -b issue/42 origin/issue/42

  user@test-machine:~/projet(issue/42)$ # On est prêt

</pre>

On garde un shell sur la machine de test, on y reviendra souvent, à

moins d’être très fort et de tout réussir du premier coup.

h2. Les commits, c’est radioactif ?

Un commit, c’est un instantané du code à un instant « T ».

Si nous souhaitons tester l’impact de chaque commit sur un projet, il

est préférable que chacun d’eux soit fonctionnel.

Par exemple, si on modifie le nom d’une fonction ou d’une variable, on

doit, dans le même commit, modifier toutes les utilisations de l’ancien

nom.

Chaque commit se doit d’être le plus « atomique » possible.

h2. Cycle de développement et tests

# On code :

<pre>

  moi@work:~/src/projet(issue/42)$ ${EDITOR} src/bidule.py

  moi@work:~/src/projet(issue/42)$ git add src/bidule.py

  moi@work:~/src/projet(issue/42)$ git commit

</pre>

# On nettoie la machine de test :

<pre>

  user@test-machine:~/projet(issue/42)$ make uninstall

</pre>

# On met à jour le dépôt de la machine de test :

<pre>

  user@test-machine:~/projet(issue/42)$ git pull origin

</pre>

# On met en place la nouvelle version du code à tester :

<pre>

  user@test-machine:~/projet(issue/42)$ make install

</pre>

# On test, si des problèmes persistent, on boucle sur 1 et on peut même utiliser un [[GitTrucsEtAstuces#Tu-balises-quand-tu-commit|petit truc]] pour s’y retrouver dans toutes ces itérations.

h2. Publication du développement

# On détermine le nombre de modification de notre branche par rapport à la branche « master »:

<pre>

  moi@work:~/src/projet(issue/42)$ git log --oneline master..HEAD | wc -l

5

</pre>

# On nettoie notre histoire privée, dans notre exemple, à partir du 5e commit avant la fin:

<pre>

  moi@work:~/src/projet(issue/42)$ git rebase -i HEAD~5

</pre>

# On rebase sur la dernière version de la branche publique :

<pre>

  moi@work:~/src/projet(issue/42)$ git fetch origin

  moi@work:~/src/projet(issue/42)$ git rebase origin/master

</pre>

# On intègre à la branche publique :

<pre>

  moi@work:~/src/projet(issue/42)$ git checkout master

  moi@work:~/src/projet(master)$ git merge issue/42

</pre>

# On [[GitTagging|tag]] un numéro de version, dans cet exemple, nous utilisons un "timestamp":http://fr.wikipedia.org/wiki/Timestamp :

<pre>

  moi@work:~/src/projet(master)$ git tag -s -m "release/$(date +%Y%m%d.%H%M)" release/$(date +%Y%m%d.%H%M)

</pre>

# On publie :

<pre>

  moi@work:~/src/projet(master)$ git push origin

</pre>

h1. Webographie

* "Pro git book":http://git-scm.org/book/fr/

* "Git Immersion":http://gitimmersion.fr

* "Git de bas en haut (en)":http://newartisans.com/2008/04/git-from-the-bottom-up

* "Activer le complètement automatique pour Bash":http://repo.or.cz/w/git/debian.git/blob/HEAD:/contrib/completion/git-completion.bash#l24

* "Utiliser des alias Git":https://git.wiki.kernel.org/index.php/Aliases

* "A successful git branching model":http://nvie.com/posts/a-successful-git-branching-model/

* "Le principe de DaggyFixes, par mercurial":http://mercurial.selenic.com/wiki/DaggyFixes

* "Le principe de DaggyFixes, par monotone":http://wiki.monotone.ca/DaggyFixes/

* "Avoiding Git Disasters: A Gory Story":http://www.randyfay.com/node/89

* "A rebase workflow":http://www.randyfay.com/node/91

* "Simpler Rebasing (avoiding unintentional merge commits)":http://randyfay.com/node/103

* "A git workflow for agile teams":http://reinh.com/blog/2009/03/02/a-git-workflow-for-agile-teams.html

* "The case for git rebase":http://darwinweb.net/articles/the-case-for-git-rebase

* "Maintaining a project":http://git-scm.org/book/ch5-3.html

* "Packaging software using Git":http://www.golden-gryphon.com/software/misc/packaging.html

* "Packaging with git":http://wiki.debian.org/PackagingWithGit/

* "Software Branching and Parallel Universes":http://www.codinghorror.com/blog/2007/10/software-branching-and-parallel-universes.html

* "Using signed tag in pull requests":http://git-blame.blogspot.com/2012/01/using-signed-tag-in-pull-requests.html

* "Trouver la source des cherry-pick avec git ?":http://stackoverflow.com/questions/2922652/git-is-there-a-way-to-figure-out-where-a-commit-was-cherry-picked-from

* "Making Sense of Revision-Control Systems":http://cacm.acm.org/magazines/2009/9/38901-making-sense-of-revision-control-systems/fulltext

* "One best practice workflow with git":http://wildfalcon.com/archives/2008/05/05/best-practice-work-flow-with-git/

* "GitGuys":http://www.gitguys.com/