Développement:CVS pour développeurs

CVS est un acronyme pour l'expression anglaise Concurrent Versioning System. Il s'agit d'un système très répandu permettant la gestion du code source de gros projets logiciels. CVS conserve toutes les versions de tous les fichiers, afin que rien ne soit jamais perdu, et de sorte que l'utilisation des personnes l'utilisant puisse être tracée. CVS fournit également un moyen de fusionner du code lorsque deux ou plusieurs personnes travaillent sur le même fichier. Tout le code et toutes les versions sont stockées sur un serveur central (dans le cas de Moodle, sur cvs.moodle.org). Le CVS book (en anglais) contient sur le CVS plus d'informations que celles dont vous avez besoin.

Si vous voulez simplement télécharger Moodle en utilisant CVS pour créer un site, vous n'avez sans doute pas besoin de cette page - voyez plutôt CVS pour administrateurs.

Joindre le projet comme développeur

Donc, on vient de vous offrir un accès en écriture au CVS pour que vous nous aidiez à développer et entretenir Moodle ! Bienvenue à bord !

Pour pouvoir écrire des modifications dans l'archive CVS de Moodle, vous devez posséder un compte avec les droits d'écriture. Pour demander un tel compte, cliquez sur l'onglet "Apply for CVS Access" sur la page CVS sur Moodle.org (http://moodle.org/cvs), et expliquez (en anglais) sur quel module vous souhaitez travailler, et pourquoi, afin que l'on puisse vous configurer un compte en vous donnant accès en écriture aux dossiers Moodle spécifiques. Un délai d'une journée ou deux pourra être nécessaire afin de vous ouvrir le compte.

Une fois ceci fait, vous aurez toutes les autorisations nécessaires. Il ne vous restera qu'à télécharger les sources actuelles de Moodle et à configurer votre machine pour travailler dessus.

Pour les exemples de cette page, nous considérerons que votre nom d'utilisateur est myusername et que votre mot de passe est mypassword.

Modules CVS

Dans le contexte de CVS, le terme modules fait référence aux différentes collections de code. Dans Moodle, l'archive CVS compte les modules suivants :

• moodle - le code source de Moodle proprement dit
• contrib - les contributions d'utilisateurs et autre code source de fonctionnalités en développement
• mysql - une version de phpMyAdmin adaptée à Moodle pour l'administration de sa base de données
• windows-cron - un petit paquetage qui rend possible l'utilisation de cron sur les systèmes Windows
• docs - diverses documentations supplémentaires fournies par des utilisateurs

La plupart des développeurs travaillent sur les fonctionnalités existantes du module moodle. Toutefois, d'autres développent également de nouvelles idées dans le module contrib. Quand le code atteint un niveau suffisant de maturité dans la zone contrib, il peut être déplacé dans le module principal moodle.

Commandes CVS de base

CVS sur Unix

Le CVS de Moodle utilise ssh comme couche de transport, pour des raisons de sécurité. Il vous sera donc nécessaire de définir une variable d'environnement CVS_RSH dans votre shell Unix. Le mieux est de placer les commandes ci-dessous dans votre fichier .bashrc ou .cshrc, de sorte que vous n'ayez pas à les retaper à chaque fois :

       setenv CVS_RSH ssh (pour csh, tcsh, etc.)
       export CVS_RSH=ssh (pour sh, bash, etc.)

Ensuite, vous pouvez télécharger sur votre ordinateur la dernière version de développement de Moodle en tapant ceci (le tout sur une ligne). Attention ! Ne lancez pas cette commande dans un dossier contenant déjà une installation de Moodle ; commencez dans un dossier vide !

       cvs -z3 -d:ext:myusername@cvs.moodle.org:/cvsroot/moodle co moodle

Utilisez une commande analogue pour les autres modules CVS :

       cvs -z3 -d:ext:myusername@cvs.moodle.org:/cvsroot/moodle co contrib

Votre mot de passe mypassword vous sera demandé pour chaque commande, à moins que vous n'ayez mis en place des clefs d'autorisation.

Vous devriez disposer maintenant d'un nouveau dossier moodle. Vous pouvez le renommer ou le déplacer à votre guise. Placez-vous dans ce dossier :

       cd moodle

La totalité des fichiers Moodle, dans leur dernière version, devraient s'y trouver. Vous pouvez maintenant modifier les fichiers de votre copie locale. Pour comparer vos fichier et dossiers avec ceux du serveur CVS, utilisez la commande cvs diff, par exemple :

       cvs diff -c config-dist.php
       cvs diff -c lang

Pour télécharger les dernières mises à jour depuis le serveur, tapez :

       cvs update -dP

Pour copier vos nouveaux fichiers vers le serveur, vous taperez quelque chose comme :

       cd lang/fr_utf8
       cvs commit

Vous pourrez indiquer un commentaire (cela dépendra de votre éditeur de texte par défaut). Veuillez écrire un texte bref et descriptif et indiquez toujours l'identifiant (du traqueur de bogues) du problème que vous êtes en train de traiter, par exemple MDL-XXXX.

Vos modifications seront alors envoyées et stockées dans le CVS. C'est tout !

Pour gagner du temps, vous pouvez placer les arguments de vos commandes par défaut dans un fichier dénommé .cvsrc dans votre dossier de démarrage. Par exemple, il pourrait contenir :

       diff -c
       update -dP

Tapez cvs help si vous avez besoin de plus de détails !

CVS sur Mac OSX

La procédure est exactement identique à celle utilisée depuis un ordinateur Unix. Toutefois, pour utiliser CVS avec Mac OS X, vous devrez auparavant installer les outils de développement (XCode Tools) de Mac OS X.

Si vous ne savez pas si les Xcode Tools sont installés sur votre Mac, jetez un coup d'oeil à la racine de votre disque dur de démarrage. Si un dossier Developer s'y trouve, vous n'avez rien de plus à effectuer.

Si vous ne trouvez pas ce dossier sur votre disque dur, vous devrez l'installer avant de pouvoir utiliser les instructions de ce document (ci-dessus). Le paquetage d'installation des Xcode Tools est disponible sur le DVD ou l'un des CD d'installation de Mac OS X.

Si vous ne trouvez plus vos CD ou votre DVD d'installation, vous pouvez aussi télécharger les Xcode Tools à l'adresse http://developer.apple.com/tools/xcode/. C'est gratuit, mais vous devrez vous enregistrer (gratuitement) comme développeur. Veuillez noter que ces outils de développement sont assez volumineux et que le téléchargement durera donc plusieurs minutes.

Comme Mac OS X est un Unix, les mêmes instructions que pour Unix (ci-dessus) peuvent alors être suivies. Tapez les commandes dans une fenêtre Terminal.

CVS sur Windows

Tout d'abord, vous devez télécharger une toute nouvelle copie de Moodle en utilisant votre compte développeur.

1. Téléchargez et installez TortoiseCVS (à partir de tortoisecvs.org), puis rebootez.

2. Créez ou identifiez un répertoire dans lequel vous voulez installer la version de travail de Moodle.

3. Cliquez-droit sur ce répertoire et activez le menu "CVS Checkout". Vous verrez apparaître une boîte de dialogue.

4. Copiez le texte suivant dans le champ CVSROOT (utilisez votre login à vous !):

          :ext:myusername@cvs.moodle.org:/cvsroot/moodle

5. Dans le champ "Module", tapez "moodle" pour récupérer la dernière version de développement de Moodle, "contrib" pour récupérer une copie des répertoires contributifs, ou "mysql" pour récupérer le module d'administration MySQL.

6. Cliquez sur le bouton "OK" et tout ce que vous avez demandé sear téléchargé.

Un boîte de dialogue vous montrera la liste des fichiers téléchargés, et au bout d'un moment vous devriez avoir une version complète de Moodle sur votre machine. Une fois cette première installation effectuée, vous n'aurez plus qu'à venir chercher les dernières mises à jours de fichiers sur le serveur CVS :

1. Cliquez-droit sur un répertoire ou un fichier quelconque de l'arborescence de Moodle et activez le menu "CVS Update".
2. Asseyez-vous confortablement et observez les lignes de journalisation qui défilent au fur et à mesure de la procédure. Notez les conflits qui vous sont signalés, indiquant une incompatibilité entre votre code et le code qui a été maintenu sur le serveur CVS - vous devrez reprendre ces fichiers à la main et résoudre les conflits qui ont été marqués dans le code source.

Après avoir modifié les fichiers (les icônes passent du vert au rouge !), vous pouvez valider vos modifications dans le serveur CVS comme ceci :

1. Cliquez-droit sur le répertoire ou le fichier Moodle à mettre à jour et activez le menu "CVS Commit...".
2. Dans la boîte de dialogue, tapez une description courte et explicite des modifications que vous venez d'effectuer. Citez le plus souvent possible une référence à un défaut déjà enregistré dans le traqueur de défauts officiel de Moodle (ex. MDL-XXXX).
3. Clickez "OK". Vos modifications seront envoyées vers le serveur.
4. Si vous créez un répertoire, PRENEZ GARDE au fait que l'ajout du répertoire dans le serveur CVS par l'opération "CVS Add" ne demande pas de confirmation (Commit). Une fois ajouté, le répertoire NE PEUT PLUS ETRE ENLEVE DU CVS même s'il est par la suite ignoré parce qu'il serait vide.

Utiliser les branches

Le diagramme ci-dessous montre comment le module CVS principal moodle bourgeonne en différentes versions au cours du temps.

Pour avoir une liste complète de toutes les balises CVS et de toutes les branches disponibles, tapez cette commande sur un fichier suffisamment ancien (par exemple index.php dans le dossier moodle) :

   cvs status -v index.php

Quelques recommandations au sujet des balises :

• les noms des balises et des branches doivent toujours être en majuscules ;
• les balises et les branches doivent toujours être appliquées à l'intégralité du module (c'est-à-dire à la totalité de Moodle). N'appliquez pas de balises sur des fichiers ou des dossiers isolés ;
• il n'est pas permis de renommer les balises, car les développeurs se basent parfois sur leur nom. Tâchez donc de les écrire correctement du premier coup !

Développement du tronc

Le "tronc" du CVS et la version de développement principale de Moodle. Dans le système de versionnement CVS, on l'appelle également HEAD, ou encore la branche par défaut.

Les développeurs Moodle essaient de maintenir ce tronc le plus stable possible, mais comme il sert à mémoriser et partager les nouvelles implémentations, il est possible d'y trouver des bugs et quelques régressions fonctionnelles.

De temps en temps nous décidons que le produit dispose de suffisamment de fonctionnalités pour produire une nouvelle distribution. A ce moment, le tronc est marqué par l'étiquette MOODLE_XX_BETA (dans le cas ou nous souhaiterions revenir à ce point précis du développement) et une nouvelle branche est créée, spécialement pour cette distribution, et nous l'appelons MOODLE_XX_STABLE.

Une archive Beta est constituée à ce moment et diffusée en téléchargement - nous le faisons pour les testeurs qui n'utilisent pas le CVS, mais veulent tester les nouvelles fonctionnalités et reporter les défauts.

Branche stable pour chaque version

Dès que la branche MOODLE_XX_STABLE est créée, l'effort de développement se divise en deux pendant un moment. Certaines personnes continueront à travailler sur des nouvelles fonctionnalités dans le tronc, en vue de la version suivante, mais la plupart des développeurs devraient concentrer leur attention sur la branche STABLE pour réduire les défauts qui y restent.

Vous pouvez synchroniser votre copie locale de Moodle sur la version STABLE en utilisant la commande suivante (Unix) à partir de la racine d'installation de Moodle :

   cvs update -dP -r MOODLE_XX_STABLE

Immédiatement après cette opération, toutes les commandes décrites ci-après s'appliqueront à cette version stable. Pour rétablir le code du tronc, il vous suffit d'exécuter :

   cvs update -dPA

Sur les clients Windows, une liste déroulante vous permet de sélectionner la branche pour les commandes update ou checkout.

Une fois que la branche STABLE se stabilise réellement, une distribution stable peut être publiée. L'archive de distribution est créée et la branche est alors étiquetée (par Martin Dougiamas) au nom de : MOODLE_XXX

Propager les corrections de bug

Toute correction de bug dans une branche STABLE devrait être propagée dans le tronc pour que les versions suivantes de Moodle puissent en bénéficier. Une étiquette flottante appelée MOODLE_XX_MERGED doit être gérée pour marquer les correspondances les plus récentes avec le tronc. La procédure pour gérer ce marqueur est la suivante (j'utilise la ligne de commande CVS sur Unix mais la procédure est identique quelque soit le client CVS) :

1. Je recommande vivement de constituer localement une copie de référence de chaque branche stable ainsi que du tronc afin de pouvoir facilement aller de l'une à l'autre. Chacune de ces versions peut être activée comme un hôte virtuel sur votre machine locale. J'utilise pour ma part des répertoires /moodle/18, /moodle/19 /moodle/dev etc.

2. Mettez à jour les fichiers qui vous concernent dans la version stable (j'utiliserai XX dans l'exemple, mais cela pourrait être 18, 19, etc), et lancez un "CVS diff" pour effectuer la double vérification sur ce dont vous disposez réellement. Notez que vous n'avez besoin de mettre à jour que les fichiers (resp. répertoires) sur lesquels vous travaillez, mais parfois il peut être utile de faire une mise à jour générale des fichiers pour maintenir sa plate-forme à jour de tout ce qui est modifié.

         cd /moodle/XX/user
         cvs update -dPA
         cvs diff -c file1.php file2.php

3. Si tout a l'air bon, modifiez les fichiers pour corriger le bug et soumettez les au serveur. Assurez-vous que le message de commentaire de la soumission comporte bien l'identifiant (ex. MDL-1111) du défaut que vous corrigez ainsi qu'une explication courte mais suffisante de votre modification. Si vous ne définissez pas de message en ligne de commande, une saisie interactive vous sera proposée pour en taper un.

         cvs commit -m "MDL-1234 Corrected a small typo in the user name field" file1.php file2.php

4. Allez à la version la plus récente de Moodle (le tronc). Effectuez une mise à jour complète du code de cette version, ou du moins, du répertoire qui vous concerne.

         cd /moodle/dev/user
         cvs update -dPA

5. Effectuez le report des modifications des branches stables dans le tronc, à partir de la dernière situation reportée connue (il s'agit de propager toutes les modifications ultérieures à la position de l'indicateur MOODLE_XX_MERGED). Vous pouvez ré-exécuter la séquence (4) et (5) pour propager les modifications vers d'autres branches stables (afin de synchroniser des versions antérieures avec vos modifications).

         cvs update -kk -j MOODLE_XX_MERGED -j MOODLE_XX_STABLE file1.php file2.php

6. Vérifiez attentivement le rapport de mise à jour en quête d'éventuels conflits, et résolvez ces derniers. Après coup, vous pourrez effectuer un "CVS Diff" pour vérifier que tout est en ordre :

         cvs diff -c file1.php file2.php

7. Soumettez à nouveau les modifications locales provoquées par les reports dans le tronc du CVS :

         cvs commit -m "MDL-1234 Corrected a small typo in the user name field, merged from XX" file1.php file2.php

8. Retournez à votre version de branche :

         cd /moodle/XX/user

9. Mettez à jour les indicateurs flottants MOODLE_XX_MERGE (il coïncideront avec l'étiquette MOODLE_XX_STABLE) de sorte de servir de point de départ pour la prochaine session

         cvs tag -RF MOODLE_XX_MERGED file1.php file2.php

Enfin, les valeurs de la variable $version de tous les fichiers version.php de Moodle de la branche stable doivent être mises à jour (on n'utilisera que les deux derniers chiffres au moins si plusieurs modifications sont faites le même jour). La raison en est que des personnes effectuant une mise à jour d'une version "très" stable vers une autre version "très" stable pourraient omettre d'exécuter des modifications de base de données nécessaires à la bonne marche du tronc.

Quelques commandes CVS utiles

Pour récupérer la version d'un fichier à une certaine date, on utilisera une commande de ce type :

     cvs update -r MOODLE_19_STABLE -D "4 Jan 2008" filename.php

et pour obtenir la distribution complète disponible à cette date, cette commande :

     cvs update -dP -r MOODLE_19_STABLE -D "4 Jan 2008"

Utiliser les branches pour des évolutions importantes

Parfois, il se peut qu'une fonctionnalité demande de nombreux changements et le travail d'un certain nombre de personnes, mais soit trop instable pour pouvoir être synchronisée dans le tronc.

Dans ces cas de figure, une branche temporaire peut être créée pour travailler précisément sur ce point, puis reportée sur le tronc aussitôt que possible. Un exemple d'une telle branche appelée MOODLE_XX_WIDGET est illustrée par le diagramme ci-après.

Si vous avez ce besoin pour votre propre fonctionnalité WIDGET, suivez cette procédure :

1. Discutez d'abord avec d'autres développeurs pour vous assurer de la pertinence du développement !

2. Ajoutez une nouvelle étiquette (pour la totalité des fichiers de moodle) appelée MOODLE_XX_WIDGET_PRE

         cvs tag -R MOODLE_XX_WIDGET_PRE

3. Créez votre branche nommée MOODLE_XX_WIDGET

         cvs tag -Rb MOODLE_XX_WIDGET

4. Travaillez dans cette branche jusqu'à ce que les modifications apportées soient suffisamment stables. Soumettez vos modifications au serveur autant que nécessaire.

         cvs commit

5. Lorsque vous êtes prêt, rabattez toute la branche dans le tronc, résolvez les conflits, soumettez les versions définitives puis abandonnez la branche.

         cvs update -dPA
         cvs update -kk -j MOODLE_XX_WIDGET
         cvs commit

Bonne chance, opérez avec prudence et éclatez-vous !

Mais qui donc est... ?

Certaines personnes contribuant au code source de Moodle possèdent des noms d'utilisateurs amusants sur le serveur CVS. Si par hasard vous jetez un œil sur une contribution sur le CVS et que vous vous demandez : "Mais qui est donc ce purpleblob ?", cette liste pourra vous aider :

diml

Valery Fremaux

jmg324

Jenny Gray (Open University)

mjollnir_

Penny Leach (Catalyst)

moodler

Martin Dougiamas (moodle.com)

scyrma

Mathieu Petit-Clair (moodle.com)

skodak

Petr Škoda (moodle.com)

stronk7

Eloy Lafuente

thepurpleblob

Howard Miller

wildgirl

Helen Foster (moodle.com)

Pour la liste complète, voir Moodle developers with write access.

Trucs, astuces et autres informations

• en:Tracking Moodle CVS with git
• Merging Custom Moodle Code With Stable Releases
• en:Unmerged files: Pour vérifier si vous avez laissé des modifications non reportées dans le tronc.
• CVS Manual
• Introduction to the contrib area of CVS

Voir aussi

• CVS pour administrateurs
• "All developers should switch to using the cvs.moodle.org alias"