Développement:CVS pour développeurs

Remarque : la traduction de cet article n'est pas terminée. N'hésitez pas à traduire tout ou partie de cette page ou à la compléter. Vous pouvez aussi utiliser la page de discussion pour vos recommandations et suggestions d'améliorations.

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 Sourceforge 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 chez Sourceforge 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

First, you need to download a completely fresh copy of Moodle using your developer account.

1. Get TortoiseCVS from tortoisecvs.org and install it, then reboot.

2. Find or create a new folder somewhere where you want Moodle to be downloaded to.

3. Right-mouse-click that folder and choose "CVS Checkout" from the menu. You should see a dialog box.

4. Copy this text into the CVSROOT field (using your own username!):

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

5. Under the "Module" field, type "moodle" to get the latest development version of Moodle, "contrib" to get the contributions directory, or "mysql" to get the MySQL Admin module.

6. Press the button: "OK" and everything should be downloaded.

A dialog box should show all the files being downloaded, and after a while you should have a complete copy of Moodle. After this first checkout, you can fetch the latest updated files from the CVS server:

1. Right-mouse-click on your Moodle folder (or any file) and select "CVS Update".
2. Sit back and watch the logs scroll by. Take note of conflicts that may occur if your local code has changes that conflict with the incoming versions - you will need to edit these files and resolve the conflicts manually.

After modifying files (you will notice their icons change from green to red!), you can commit them back to the CVS server like this:

1. Right-mouse-click on your Moodle folder (or any file) and select "CVS Commit...".
2. In the dialog box, type a clear description of the changes you are committing. Always include the name of any tracker issues related to what you are fixing (eg MDL-XXXX).
3. Click "OK". Your changes will be sent to the server.
4. If you create a folder, BE CAREFUL about using the "CVS Add" option as it will add the folder to CVS without requiring a commit. Once added, the folder cannot be removed from CVS even though it will be pruned so long as it is empty.

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 étiquettée (par Martin Dougiamas) au nom de : MOODLE_XXX

Merging fixes

All bug fixes in any STABLE branch should be merged back into the trunk so that they become available in future versions of Moodle. A floating tag called MOODLE_XX_MERGED needs to be maintained to keep track of the last merge. The procedure for such a merge is as follows (I'm using CVS on the Unix command line but the steps are the same for any CVS client):

1. I highly recommend keeping one checked out copy of each stable branch and the trunk/head version locally to make it easier to jump between them. Set them all up as virtual web sites on your development machine. I use directories like /moodle/18, /moodle/19 /moodle/dev etc.

2. Update to the latest stable version (I'll use XX in the example but it could be 18, 19 etc) for the relevant files, and do a cvs diff just to double-check exactly what you are checking in. Note you only need to update the files/directories you are working in, but sometimes it help to update everything anyway just to do a final check on the functionality using the web.

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

3. If all looks OK, check in the fix to the stable branch. Make sure that the commit message contains the bug tracker ID (eg MDL-1111) and a decent description of your thoughts on the fix. If you don't specify a message in the command line, you'll be put into an editor to type one.

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

4. Go to the very latest trunk version. I highly

         cd /moodle/dev/user
         cvs update -dPA

5. Merge everything into your local copy of the trunk from your stable branch since the last merge. You can use the same sequence of (4) and (5) to merge the changes into other stable branches too (to backport the fix to the previous stable versions).

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

6. Carefully watch the update logs for conflicts, and fix every file that you see with a conflict. Afterwards, it may help to just run a diff to make sure the result is what you expected:

         cvs diff -c file1.php file2.php

7. Check your merged local copy back into CVS trunk version

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

8. Go back to your branch version

         cd /moodle/XX/user

9. Update the floating merge tag for the affected files (so that it matches MOODLE_XX_STABLE) so that this process can be repeated next time

         cvs tag -RF MOODLE_XX_MERGED file1.php file2.php

Finally, the values for $version in all the Moodle version.php files within the stable branch should not be updated at all if possible (except the last digit if absolutely necessary). The reason is that someone updating from a very stable version to the next very stable version could miss database upgrades that happened on the trunk.

Feature branches for large changes

Occasionally, there may be a very large feature that needs to be checked in so several people can work on it, but it is too unstable to be included in the main development trunk.

In these cases a short-term branch can be created to work on the feature, and then merged back into the main trunk as soon as possible. An example called MOODLE_17_WIDGET branch can be seen in the above diagram.

If you need to do this for your new WIDGET feature, follow these steps:

1. Discuss with other developers to make sure it's necessary!

2. Make a new tag on the trunk (for all of moodle) called MOODLE_XX_WIDGET_PRE

         cvs tag -R MOODLE_XX_WIDGET_PRE

3. Create your branch called MOODLE_XX_WIDGET

         cvs tag -Rb MOODLE_XX_WIDGET

4. Work in that branch until the feature is reasonably stable. Commit as necessary.

         cvs commit

5. When ready, merge the whole branch into the trunk, fix conflicts, commit it to the trunk and then abandon the branch.

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

Good luck, be careful and have fun!

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: To see if you've forgotten to merge any file.
• CVS Manual
• Introduction to the contrib area of CVS
• "All developers should switch to using the cvs.moodle.org alias"

Voir aussi

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