EOLE

h1. À faire sur cette documentation

* TODO Mettre au clair « sur une branche » et « dans une branche »

* TODO Clarifier « on »/« nous »

* TODO Expliquer @git merge-base@

* TODO Lister les prérequis

h1. Pas taper !

Je vais essayer de décrire ici une méthodologie de travail basé sur le

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

Ce document ne représente en rien _LA_ bonne méthode de travail, il

s’agit juste, dans un premier temps, de mon opinion personnelle,

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.

Ce document n’est pas une référence git, je ne vais pas réécrire le

"progit book":http://progit.org/book/fr/, ni les autres références que l’on trouve sur Internet.

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 en 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 » ?

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 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 la règle suivante :

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

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, ça 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 fichies 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

utilisations 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.

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 utiliser 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 certains 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és 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 par 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://progit.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 ;

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

* D’un accès "SSH":http://fr.wikipedia.org/wiki/SSH 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 tous 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.

h2. Publication du développement

# On nettoie notre histoire privée :

  <pre>

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

  </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 tag un numéro de version :

  <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

* "Avoiding Git Disasters: A Gory Story":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

* "Pro git book":http://progit.org/book/ch5-3.html

* "Maintaining a project":http://progit.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/