Available nodes

Cette page est dédiée à donner quelques pistes concernant l'utilisation de Subversion, un logiciel de gestion de version, à l'intérieur des projets de 1ère année à l'ENSEIRB. Il existe un document de référence () donnant quelques pistes de réflexion supplémentaires.
Les projets se font par équipes, mais les principes décrits dans ces pages doivent être compris par chacun. A la fin de cette feuille, chaque membre de l'équipe doit avoir :

créé un répertoire de travail personnel contenant les sources de son projet;
communiqué une révision dans un des fichiers de sources à l'intérieur du projet.

Principes généraux

Lorsque l'on réalise un projet basé sur un ensemble de fichiers source, qu'il s'agisse du code d'un programme en langage C ou du source d'un rapport rédigé en LaTeX, on passe inévitablement par de nombreuses versions successives.

Une version du projet, appelée aussi , représente l'ensemble des fichiers appartenant au projet à un moment fixé de son développement, telle une photographie de son état instantané. Le projet évolue ainsi à partir de sa révision initiale vers une révision propre à sa mise en production.

Un autre problème se présente pour réaliser ce projet lorsque l'on commence à travailler à plusieurs : chaque membre de l'équipe dispose de se propre révision, et il n'est pas évident de pouvoir partager ses révisions entre les personnes.

Pour apporter une solution à ces problèmes, on adopte le système suivant :

Les sources du code sont placées dans un endroit particulier appelé dépôt, capable de stocker toutes les révisions du code. Le dépôt est unique pour le projet, et sert de référentiel sur l'état d'avancement du projet.
On ne travaille sur les sources qu'à l'intérieur d'un répertoire de travail. Chaque participant au projet peut avoir son propre répertoire de travail. Ceux-ci correspondent aux différentes modifications en cours.

Après avoir terminé les modifications sur le répertoire de travail, on peut ses modifications au dépôt pour créer une nouvelle révision. Cela permettra aux autres participants au projet de cette révision et de pouvoir travailler avec.

Créer son répertoire de travail

Cette section est à réaliser par chaque membre de l'équipe.

Copier le fichier suivant dans le fichier ~/.subversion/config.

export URL=http://www.labri.fr/perso/renault/working/teaching/projets/files && \
    mkdir -p ~/.subversion && \
    wget -q $URL/config-subversion -O ~/.subversion/config && \
    wget -q $URL/servers-subversion -O ~/.subversion/servers && \
    unset URL && echo "Subversion config updated"

Connectez-vous sur la forge de l'ENSEIRB, et rendez-vous sur la page dédiée à votre projet, et suivez plus précisément l'onglet nommé "Repository".

Cette page contient une commande suivante :

svn co https://thor.enseirb-matmeca.fr/svn/chabadabada your_local_dir

Il va sans dire qu'il n'existe pas de projet nommé chabadabada, et que copier/coller directement la commande précédente est un acte inutile.

Visualisez le contenu du dépôt en suivant le lien ci-dessus (appelé accès par WebDAV). Vous devez normalement constater qu'il est vide.

Placez vous dans un terminal, et déplacez vous dans un répertoire dans lequel vous comptez mettre les sources de vos projets. Ensuite, recopier cette commande dans le terminal et l'exécuter.

Si tout se passe correctement, le résultat devrait être de la forme :

Checked out revision 0.

La commande a créé un répertoire de travail appelé your_local_dir dans le répertoire courant, contenant la révision initiale (numérotée 0). Il est toujours possible de modifier le nom du répertoire de travail après coup. Initialement, ce répertoire ne contient que des sous-répertoires nommés .svn/

Assurez vous que chaque membre de votre équipe ait bien créé un répertoire de travail personnel. C'est important pour la suite.

Créer des fichiers et des répertoires

Cette section est à réaliser par de l'équipe. Les autres peuvent regarder.

Se positionner à l'intérieur de son répertoire de travail (à l'intérieur de celui nommé your_local_dir si vous n'avez pas changé son nom). Créer un fichier authors.txt vide.
```
touch authors.txt
```
Initialement, Subversion ne sait pas que ce fichier fait partie des sources du projet. Il est nécessaire de lui signifier l'existence du fichier en faisant :
```
svn add authors.txt
```

Cette commande indique que , le fichier authors.txt a été ajouté au répertoire de travail. Comme il s'agit d'une modification des sources, il faut la communiquer au dépôt.

Communiquer votre modification des sources avec la comande :
```
svn commit -m "Ajout du fichier authors.txt vide"
```
Vérifier que vos modifications sont bien apparues dans le dépôt, en utilisant l'accès par WebDAV.

Créer dans le répertoire de travail un répertoire nommé src. Communiquer cette nouvelle modification au dépôt en utilisant un commentaire intelligent.

Les commentaires sont une source d'information importante pour comprendre la manière dont évoluent les sources. Ils doivent être à même d'expliquer les modifications que vous venez de faire.

Mettre son répertoire de travail à la révision la plus récente

Cette section est à réaliser par les autres membres de l'équipe par rapport à la personne ayant ajouté les fichiers précédents.

Placez-vous dans votre répertoire de travail. Normalement, ce répertoire est vide, comme à sa création.
Retirer du dépôt la dernière révision des sources avec la commande :
```
svn update
```

Cette commande va demander au dépôt de transmettre la dernière révision qui lui a été communiquée, et de la placer dans le répertoire de travail. Il devient alors possible de modifier cette révision, et de la communiquer au dépôt lorsqu'on en est satisfait.

Communiquer une révision dans le dépôt

Cette section et les suivantes peuvent être réalisées par chaque membre de l'équipe.

Ajouter dans le répertoire src un fichier dont le nom est votre nom de login avec l'extension .c. Ce fichier contiendra dans un commentaire (en langage C) une petite phrase vous décrivant en quelque mots.
Communiquer cette modification au dépôt, toujours avec un commentaire précis.
```
svn commit
```
Si la commande précédente est utilisée sans passer l'option -m, Subversion exécute un éditeur dans lequel vous pouvez taper votre commentaire.

Il est possible que Subversion vous annonce que votre répertoire de travail n'est pas à jour au moment où vous faites la commande svn commit. Cela signifie que quelqu'un a modifié les sources pendant que vous travailliez dessus. Pour résoudre le problème, il suffit d'utiliser la commande

svn
    update

Se placer dans son répertoire de travail, et éditer le fichier authors.txt précédemment créé. Rajouter dans ce fichier une ligne contenant son nom et son prénom.
Que se passe t'il lorsque deux personnes modifient le fichier authors.txt de leur côté, et essaient de transmettre leur version au dépôt l'un après l'autre ?

Guide rapide pour la résolution d'un conflit

Lorsque deux personnes modifient le même fichier source en même temps, et qu'elles essaient de communiquer leurs modifications au dépôt, cela peut mener à un conflit. A priori, les conflits apparaissent après une commande svn update.

% svn commit -m "Ajout de A. Turing dans le fichier authors.txt"
Sending        authors.txt
svn: Commit failed (details follow):
svn: Out of date: 'authors.txt' in transaction '4-1'

Mettre à jour le répertoire de travail. Cela devrait donner un résultat équivalent à :
```
% svn update
C    authors.txt
Updated to revision 4.
```
La lettre 'C' indique qu'il y a un conflit lors de la mise à jour. Si l'on regarde les fichiers dans le répertoire courant, on se rend compte que Subversion a cré des fichiers et modifiéles fichiers existant.

Ouvrir le fichier authors.txt. Quelles sont les modifications ajoutées par Subversion ?
Résoudre le conflit, en modifiant le fichier authors.txt de manière à ce qu'il soit correct.
Indiquer à Subversion que le conflit est résolu :
```
svn resolved authors.txt
```
Communiquer sa révision au dépôt.

Règles de bonne conduite pour l'utilisation de Subversion

Vérifier systématiquement que son répertoire de travail est à jour
On ne sait jamais si une personne autre que soi n'a pas modifié les sources dans le dépôt. Donc, avant chaque modification, et avant chaque communication des modifications au dépôt, il faut mettre à jour son répertoire de travail avec la commande svn update.
Deux personnes doivent (autant que possible) ne pas travailler au même moment sur les mêmes fichiers.
Pour éviter d'avoir à résoudre des conflits, il vaut mieux travailler de manière à ne pas en créer. Donc, il faut essayer de ne pas faire des modifications sur les mêmes fichiers au même moment. Dans le cas d'apparition d'un conflit complexe, se référer au document .

A faire par la suite ...

Considérer la possibilité d'organiser le dépôt de manière hiérarchique en se servant des répertoires : un répertoire pour les tests, un répertoire pour la documentation, un répertoire pour les fichiers temporaires …
Considérer l'ajout d'un fichier README dans un format simple (texte ou markdown) à la racine de votre dépôt. Ce fichier pourra décrire les répertoires du projet et détailler les commandes de base permettant de compiler votre projet, d'exécuter les tests, de construire la documentation …