Attention : vous consultez actuellement la documentation dédiée aux versions 1.x de Moodle. La documentation pour les versions 2.x de Moodle est consultable ici : Développement:CVS pour développeurs, celle pour les versions 3.x de Moodle est consultable ici : Développement:CVS pour développeurs et celle pour Moodle 4.x est consultable là : Développement:CVS pour développeurs.

Développement:CVS pour développeurs

De MoodleDocs
Aller à :navigation, rechercher

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 les serveurs de Sourceforge). 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 contacter Martin Dougiamas de sorte qu'il puisse vous configurer un compte en vous donnant accès en écriture aux dossiers Moodle spécifiques.

Pour éviter de devoir taper votre mot de passe chaque fois que vous lancez une commande CVS, vous devrez générer une paire de clefs publique/privée et envoyer la clef publique à Martin Dougiamas. Les explications données par Sourceforge pour l'utilisation de clefs d'autorisation pourront vous être utiles. Cette étape est optionnelle, mais rendra votre travail avec CVS beaucoup plus agréable.

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.

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.

Moodle4Mac Update4.png

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.

Moodle4Mac Update5.png

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.

CVS tree

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

The Trunk of CVS is the main development version of Moodle. In CVS it is also known as the HEAD, or default branch.

Moodle developers try to keep this stable as possible, but as it usually contains new code it probably has bugs and small instabilities.

Every now and then we decide the product has enough features to make a release. At this time, the trunk is tagged with a MOODLE_XX_BETA tag (in case we ever want to roll back to that point) and a new branch is formed for the release, called MOODLE_XX_STABLE.

A Beta package is also released at this point - it's for testers who don't use CVS but want to test the latest features and report bugs.

Branche stable pour chaque version

As soon as the stable branch MOODLE_XX_STABLE is created, development efforts will fork into two streams for a while. Some people may continue working on new features in the trunk for the next release, but most developers should be concentrating on using the current STABLE branch and fixing bugs that are found in it.

You can switch your local copy of Moodle to the STABLE version using the following command in Unix from the root directory:

   cvs update -dP -r MOODLE_XX_STABLE

After that, all the commands described above will apply to that stable version. To return to the trunk version just issue:

   cvs update -dPA

On Windows clients you should have a menu from which you can choose the branch.

Once the new STABLE branch really stabilises, a release can be declared. Packages are created for distribution and the branch will be tagged (by Martin Dougiamas) with a tag named: 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!

Trucs, astuces et autres informations

Voir aussi