University of Avignon and Open Source Software

Comme promis, nous allons dans ce billet donner une rapide introduction à l’utilisation de Git pour les administrateurs système souhaitant gérer les mises à jour de leurs installations, ainsi que pour les contributeurs dans une seconde partie.

Utilisation du dépôt pour maintenir facilement votre installation

Première récupération des sources

Vous voulez récupérer les sources de FileZ ou RdvZ avec Git et vous avez bien raison, voici donc quelques explications. FileZ et RdvZ sont des projets appartenant à l’utilisateur UAPV sur GitHub, vous pouvez donc les voir à cette adresse : http://github.com/UAPV. En consultant la page de ces projets, vous pouvez récupérer l’URL du dépôt qui s’initialise comme ceci :

git clone git://github.com/UAPV/RdvZ.git rdvz

Vous voilà donc avec une copie du dépôt courant sur votre machine !

Choisir la version utilisée

Hormis si vous souhaitez tester une nouvelle fonctionnalité, il est déconseillé de se placer sur la dernière modification envoyée par un développeur. Il sera préférable d’utiliser un tag ou une branche pour s’assurer de la stabilité de votre installation. Nos dépôt sont (seront) organisé de la manière suivante :

• Chaque version mineure (ex: 2.0, 2.1) possèdera sa branche
• Chaque version de maintenance (ex: 2.0.1, 2.0.2) sera tagguée.

Choisir un branche vous permettra de récupérer les dernières corrections de bug tandis que les tags vous permettront de choisir plus finement votre version. Utiliser une des deux commandes suivantes pour lister les branches ou tags :

git branch
git tag

Il suffit ensuite d’utiliser la commande “git checkout” pour se déplacer dans l’historique du dépôt :

git checkout 2.0 # pour la branche 2.0 par exemple
git checkout 2.0.1 # pour le tag 2.0.1

Mettre à jour vos sources

Nos applications libres évoluent selon vos contributions et nos idées, de nouvelles versions incluant des corrections de bugs ou des nouvelles fonctionnalités sont mises en ligne assez souvent. Si vous avez suivi l’étape précédente et que vous avez un dépôt local, vous n’avez qu’à taper cette commande pour récupérer les dernières mises à jour :

git fetch

Tous les commits qui ont eu lieu sont récupérés et un résumé des changements, nouveaux tags ou branches est affiché. Pensez à faire un checkout pour vous déplacer vers ces nouveaux tags ou branches.

Contribuer

Git apporte de nombreuse fonctionnalités qu’il n’est pas évident de prendre en main lorsqu’on vient d’un gestionnaire plus classique comme Svn. La difficulté principale consiste à se détacher des concepts plutôt simples de Svn pour visualiser clairement la notion d’arbre décentralisé. Des très bonnes lectures pour commencer et comprendre le fonctionnement interne des branches et dépôts distant sont les livres ProGit disponible gratuitement et Git Community Book. Le site GitRef.org vous servira ensuite de référence pour vous accompagner au quotidiens.

Forker un dépôt

Un des grands intérêts de GitHub est de permettre le “fork” de dépôts. Il s’agît en réalité d’effectuer une copie publique d’un projet qui va vous appartenir et que vous allez pouvoir modifier à volonté. Une fois les modifications effectuées, il est possible de demander au développeur originel du projet si les changements peuvent être intégrés au projet principal grâce à un “pull request”. L’intérêt de cette pratique est évident dans le cas de projets open source appelant à la contribution communautaire comme les notres. Les paragraphes suivants vont essayer de décrire la ligne de conduite couramment utilisée dans les projet git, il est important de la suivre pour faciliter l’intégration future de votre travail.

Git workflow

La suite de ce tutoriel va présenter une des solutions “best practice” pour contribuer à un projet en utilisant Git.

“Branchez”

Créer une branche est simple et léger sous git, il ne faut pas s’en priver, cela permettra de distinguer facilement votre travail pour qu’il soit évalué par l’intégrateur. Ce type de branche est également appelé “topic branch”

git checkout -b new_feature

Vous pouvez alors commencer votre travail en commitant régulièrement.

git add modified_file.php
git commit -m "Fixed  foobar function..."

“Rebasez”

Pour faciliter le travail de l’intégrateur nous allons lui éviter d’éventuels conflits en utilisant la commande “rebase”. Cette commande a pour effet de réorganiser votre branche “new_feature” sur la dernier commit du dépôt original. Ainsi au lieu d’avoir la configuration suivante (X,Y,Z sont vos commit sur votre topic branche) :

A--B--C--D--E--F
       \
        X--Y--Z

Vous obtiendrez ceci après un rebase :

 A--B--C--D--E--F
                 \
                  X'--Y'--Z'

Pour réaliser cette opération il faut d’abord récupérer les derniers commits du projet original dans votre dépôt à l’aide d’une “remote branch”. Nous appelerons cette branche “upstream” :

git checkout master # On se replace sur la branche principale de notre fork
git remote add upstream git://github.com/UAPV/FileZ.git
git pull upstream master # On récupère les dernières modifs dans la branche principale du fork
git checkout new_feature # On peut retourner sur notre feature branch

On peut alors réorganiser nos commits sur la tête de la branche “master” :

git rebase master

En ajoutant l’option “-i” à commande précédente il est également possible de fusionner les commits X, Y, Z en un seul. En tapant “git rebase -i master” un éditeur s’ouvrira; Remplacez alors tous les “pick” SAUF le premier par des “squash”. Vous obtiendrez alors un historique plus simple pour l’intégrateur :

 A--B--C--D--E--F--XYZ

Attention, la commande rebase est à éviter sur des commit ayant déjà été partagés et sur lesquels d’autres personnes ont basé leurs modifications; De la même manière que Marty dans “Retour vers le futur”, il faut être prudent.

Partagez

La dernière étape consiste à rendre visible votre travail en l’envoyant sur github :

git push origin new_feature

Vous pouvez maintenant effectuer un “pull request” sur github pour notifier le mainteneur du projet que votre patch est prêt.

Ce tutoriel n’aurait certainement pas vu le jour si la documentation de contribution de Symfony2 était sortie quelques jours plus tôt.  Leurs explications sont en effet plus détaillées et correspond exactement à la marche à suivre que nous vous conseillons d’adopter. Toutefois, il est important de lire un minimum de documentation pour réussir à perdre les réflexes de subversion et comprendre les branches de Git.