Tutorial d`utilisation de la forge MAGE

Tutorial d’utilisation de la
forge MAGE
Tutorial
Référence
:
T
Version
:
1.1
Date
:
02/02/2010
Auteur(s)
:
Laurence Estrabaut
TABLE DES MATIERES
1
PRESENTATION GENERALE DE LA FORGE ..............................................3
1.1
PAGE D’ACCUEIL ..................................................................................................3
1.2
CREATION DE PROJET ..........................................................................................4
1.3
L’ESPACE PROJET .................................................................................................6
2
SUBVERSION......................................................................................................12
2.1
PRINCIPE GENERAL ............................................................................................12
2.2
ILLUSTRATION VIA NETBEANS ...........................................................................13
2.2.1
L’IMPORT D’UN PROJET SOUS SUBVERSION ...............................................13
2.2.2
RECUPERER UN PROJET DEJA VERSIONNE ..................................................17
2.3
LA GESTION DE CONFLIT ....................................................................................22
2.3.1
LE CONFLIT SIMPLE : RESOLUTION PAR FUSION .........................................23
2.3.2
LE CONFLIT COMPLEXE : INTERVENTION DE L’UTILISATEUR .....................26
2.3.3
LE « TAGUAGE » DE VERSION ...................................................................28
-2-
1 PRESENTATION GENERALE DE LA FORGE
Une forge est un système de gestion de développement collaboratif de projets
informatiques. L’outil central d’un tel système est le système d’archivage des sources du
projet. Dans la forge retenue, il s’agit de Subversion, successeur de CVS.
Un panel d’outils divers destinés à l’animation de la communauté crée autour du
projet est également disponible. Il s’agit d’outils de communication (chat, blog, forum,
…) et de diffusion (zone de téléchargement).
L’équipe MAGE s’est dotée d’un tel système, accessible via Internet et disponible
à l’adresse suivante : http://forge-mage.g2elab.grenoble-inp.fr
1.1
PAGE D’ACCUEIL
Voici ci-dessous une impression écran de la page d’accueil de la forge de l’équipe
MAGE.
1
2
3
4
Fig. 1 : Page d’accueil de la forge Mage.
1 : Cartouche d’identification : permet à l’utilisateur de s’identifier en entrant sur la
forge. Permet également à l’utilisateur de modifier son profil et d’accéder à son espace
personnel de stockage de documents : le porte-documents.
-3-
2 : Les onglets de navigation : permet de naviguer au sein de la forge. Le premier
onglet ramène à la page d’accueil. Le second permet d’accéder à l’explorateur de projets.
Le troisième (inactif pour le moment) amène au salon de discussion en ligne. Le
quatrième est le bloc-notes. Le bloc-notes est commun à l’ensemble de la forge. Il permet
de laisser des messages à l’ensemble de la communauté.
3 : Recherche et ajout de projets : au même niveau se trouve la recherche sur mots-clés
et l’ajout de projet.
4 : la zone d’activité : cette zone découpée en plusieurs parties présente les derniers
« mouvements » autour des projets : actualités récentes, téléchargements, créations, …
1.2
CREATION DE PROJET
Un click sur le lien « Ajouter un projet » amène l’utilisateur à la page de création
d’un projet. L’écran suivant présente cette page et les différents champs à remplir. Les
champs marqués d’une étoile rouge sont obligatoires.
Fig.2 : Pane d’ajout d’un projet
Nous allons créer un projet nommé « mon_projet » qui nous servira d’exemple
tout au long de ce tutorial. Après avoir renseigné son nom et le nom utilisé pour l’url du
projet (nom qui sera également celui du repository attaché à ce projet), n’oubliez pas
d’indiquer également la catégorie d’appartenance du projet.
-4-
Les dernières informations à fournir concernent, les langages utilisés, les
traductions disponibles et la licence d’utilisation. Ces informations sont modifiables à
tout moment par édition du projet.
Fig.3 : N’oubliez pas d’indiquer la catégorie de votre projet
Après sa création, le projet doit être validé par un administrateur. Une fois fait, le
projet est accessible via la page d’accueil ou l’onglet des projets.
-5-
1.3
L’ESPACE PROJET
Chaque projet dispose d’un espace web qui lui est propre et pour lequel on
retrouve les outils évoqués précédemment.
Comme pour la page d’accueil, une série d’onglets permet de naviguer au sein du
projet et d’accéder aux différentes fonctionnalités disponibles.
1
2
3
4
5
6
7
8
9
Fig. 4 : La page d’accueil du projet permet d’accéder, au travers d’onglets de navigation à touts ses fonctionnalités et
outils.
1 : Projet : cet onglet ramène l’utilisateur à la page d’accueil du projet. Sur cette
page figure les informations saisies lors de la création et les fonctionnalités
d’administration du projet. L’administrateur du projet nommé chef de projet peut en
effet créer une version du projet et/ou rajouter des collaborateurs au projet. Seuls les
collaborateurs auront le droit de faire des modifications sur les sources. Pour le moment,
la forge ne propose pas plusieurs type de contributeurs. C’est une évolution attendue et
prévue.
-6-
Fig.5 : Les panels sur fond couleur saumon sont des panels d’administration. Selon leur niveau de droits, les
utilisateurs peuvent les voir ou non. Celui-ci permet de créer une version du projet et d’ajouter un contributeur au
projet.
2 : Journal : cette section est alimentée automatiquement par les actions menées
sur le projet.
3 : Téléchargement : c’est dans cette zone que le chef de projet peut organiser
les téléchargements des différentes versions du projet. Le principe est d’associer un ou
plusieurs fichiers à un numéro de version préalablement crée sur la page d’accueil du
projet.
Fig. 6 : L’ajout de fichier en téléchargement se fait par rapport à une version du projet. Vous devez donc créer une version
avant de pouvoir uploader des fichiers.
-7-
Fig. 7 : La forge permet l’upload d’exécutables, de fichiers .pdfs ou autre. Elle permet également l’ajout de fichiers de
grande taille.
4 : Code : permet d’accéder à l’explorateur du code source déposé sur la forge via
le système de versionnement Subversion. Cependant, cette fonctionnalité peut-être
désactivée pour maintenir la confidentialité des sources déposées.
5 : Gestionnaire : permet de signaler un bug ou une anomalie mais également de
faire la demande de nouvelles fonctionnalités. Une fois une anomalie signalée ou une
demande de fonctionnalité émise par un utilisateur, il revient au chef de projet de la
« confirmer » puis d’éventuellement lui affecter un collaborateur. Il est possible d’ajouter
un fichier à la fiche de signalement et de la commenter.
-8-
Fig. 8 : le rapport d’anomalies ou « bug tracker » est un excellent outil pour faire évoluer ses projets
et rester à l’écoute de ses utilisateurs.
-9-
6 : Documentation : la documentation est sous forme d’une feuille de type wiki
que vous pouvez modifier à loisir.
Fig. 9 : Une page Wiki a sa syntaxe propre. Mais l’éditeur WYSIWYG permet d’avoir une rédaction simplifiée. Seul la
création des liens entre les différentes pages demande une syntaxe particulière.
Un wiki permet également de créer une arborescence de pages liées entre elles
comme un mini-site web éditable en ligne. Pour créer une nouvelle page wiki,
commencer par créer un lien vers cette nouvelle page simplement en insérant son nom
dans la page en cours d’édition. Pour signifier au système que ce nom pointe vers une
page wiki vous devez respectez la contrainte suivante : le nom de la page doit être
composé de plusieurs mots accolés. Exemple : MaPageWiki.
Pour avoir un rendu plus lisible vous pouvez associer le nom de cette page à un
titre plus fonctionnel de la sorte :
[wiki=NomDeLaPage nom du lien]
Sauvegardez la page en cours en cliquant sur « Editer » et suivez le lien ainsi crée
pour accéder à la nouvelle page et la modifier.
- 10 -
7 : Actualités : les actualités sont les derniers événements marquants. A l’inverse
du journal, vous devez explicitement créer vos news. Ce peut-être la création du projet, la
sortie d’une nouvelle version ou d’un patch …
8 : Forum : Le forum de discussion se découpe en 4 sous-forums :
•
aide
•
développement
•
commentaires d’utilisateurs
•
général
9 : Salon de discussion : inactif pour le moment, il permettra à terme le dialogue
en ligne.
Fig.10 : Il est essentiel de faire vivre la communauté d’auteurs et/ou d’utilisateurs autour de votre projet en communiquant les derniers événements
importants.
- 11 -
2 SUBVERSION
2.1
PRINCIPE GENERAL
L’emploi d’un système d’archivage comme Subversion est indépendant de
l’utilisation d’une forge. La forge n’est pas une application cliente de Subversion. C’est
une couche logicielle supplémentaire qui apporte un plus-produit au simple
versionnement du projet. NetBeans, Tortoise sont des applications clientes de
Subversion. Dans la suite de ce tutorial nous illustrerons les principes énoncés dans ce
chapitre avec NeatBeans 6.5.1 (version anglaise).
Le principe de l’archivage sous subversion, appelé également versionnement est
relativement simple. Les données (textuel, binaire, …) sont conservées sur le serveur qui
contient l’historique de chaque fichier archivé. Par version, on entend le numéro associé
à chaque fichier qui indique son évolution depuis sa création. Le principe de ce
numérotage est le suivant : ce numéro est composé de chiffres séparé par un point. Le
premier chiffre correspond à la version du document, le second à une modification, le
troisième à une correction.
Par exemple : un fichier en version 1.2.0 va passer en version 1.2.1 suite à la
correction d’un bug mineur, en version 1.3.0 suite à la modification d’une procédure de
parsing et en version 2.0.0 suite à l’ajout de nouvelles fonctionnalités. Le changement de
chiffre reste assez subjectif.
Il peut arriver qu’un client Subversion ne prenne en charge que les deux premiers
niveaux de versionnement.
L’espace disque du serveur dédié à l’archivage du projet est nommé repository.
La copie des sources d’un projet sur le serveur Subversion porte le nom d’export.
Cette opération n’est effectuée qu’une seule fois.
L’opération consistant à récupérer les sources d’un projet du repository est
appelée checkout. Cette opération n’est effectuée également qu’une seule fois.
Subversion crée une copie locale des dernières sources archivées sur le serveur.
Une fois récupérées, les données peuvent être modifiées localement. Ensuite,
quand les modifications sont terminées, elles sont répercutées sur le serveur. Cette
opération porte le nom de commit. Comme un fichier peut être utilisé et donc modifié
par plusieurs personnes simultanément, il se peut que la version locale (avant
modifications) ne corresponde plus à la version archivée sur le serveur (un autre
développeur ayant fait et répercuté des modifications). Il y a alors conflit entre les
versions. Subversion demande alors de mettre à jour la copie locale en faisant un update
avant de répercuter les modifications avec un commit. Le plus souvent, le conflit porte
sur des parties différentes du code et une simple fusion des deux fichiers suffit. Dans les
cas plus complexes, Subversion permet de faire un différentiel des deux fichiers afin de
déterminer les portions de code à conserver (voir 3.4.2).
- 12 -
2.2
ILLUSTRATION VIA NETBEANS
Subversion présente quelques différences avec son célèbre parent CVS. La
première est dans la structuration des projets. Subversion conseille, pour chaque projet à
versionner de créer la structure suivante :
Fig.11 : Description du système de fichier propre à Subversion
Le répertoire trunk est celui qui héberge le développement en cours. Le
répertoire tags va abriter les différentes versions tagués du projet. Taguer un projet c’est
réaliser une photographie du projet et lui donner un numéro de version (1.0 pour une
version stable par exemple). C’est dans le répertoire tags que seront stockées ces photos.
Le répertoire branches contiendra quant à lui les développements parallèles au
développement principal.
Cette façon d’organiser les projets est juste une recommandation de Subversion,
en aucun cas une obligation. Sachez que NetBeans rend transparente cette structuration.
2.2.1 L’import d’un projet sous Subversion
Admettons que le projet mon_projet, correctement structuré, contiennent des
sources à archiver.
Assurez-vous de sélectionner le projet à versionner puis dans le menu
« Versioning », choisir le sous-menu « Subersion » puis « Import into Repository ». La
fenêtre suivante apparaît.
- 13 -
Le menu-déroulant de la zone 1, éditable, permet de renseigner l’adresse du
repository du projet. Pour tous les projets, et indépendamment de leur catégorisation au
sein de la forge, l’adresse du repository est de la forme :
http://svn-mage.g2elab.grenoble-inp.fr/nom_du_projet
Dans la zone 2, il vous ai demandé votre identifiant et mot de passe. Ce sont ceux
de votre compte forge. Si vous ne les renseignez pas à cette étape, ils vous seront
redemandés ultérieurement.
1
2
Fig.12 : Panel d’import vers un repository distant de Subversion
Sur la fenêtre suivante, il vous est demandé le répertoire à versionner. Par défaut,
il s’agit du développement en cours c'est-à-dire trunk.
Le message accompagnant l’import est obligatoire.
- 14 -
Fig.13 : Choix du répertoire distant et saisie du message d’import
NetBeans liste ensuite les fichiers à archiver. Finaliser l’import par un click sur le bouton
« Finish ».
- 15 -
Fig. 14 : NetBeans liste l’ensemble des fichiers à important. Il est encore possible d’en exclure en cliquant dans la colonne
« Commit Action ».
La forge permet de visualiser le code soumis dans l’onglet « Code ».
Fig. 15 : Visualisation du code archivé par le système de browser de la forge.
- 16 -
2.2.2 Récupérer un projet déjà versionné
L’opération consistant à récupérer les sources d’un projet déjà sous gestion SVN
s’appelle le checkout.
Fig.14 : Option check-out du menu Subversion
Choisir dans le menu « Versionning » de NetBeans le menu « Subversion »
puis « Checkout.
- 17 -
En théorie, la plupart des projets ne nécessite pas d’identification préalable au
checkout. Vous pouvez donc récupérer un projet sans renseigner votre nom d’utilisateur
et votre mot de passe. Si ce n’était pas le cas, NetBeans signalera ne pas avoir
l’autorisation d’accéder au repository. Indiquer à ce moment là, votre login et mot de
passe.
L’url du repository du projet est construit sur la forme :
http://svn-mage.g2elab.grenoble-inp.fr/nom_du_repository _du_projet
Pour rappel, le nom du repository du projet est le nom du projet écrit tout en
minuscule et tous les mots le composant accolés. C’est le nom figurant dans la barre
d’adresse quand vous êtes sur la page d’accueil du projet.
Fig. 15 : choisir le projet à récupérer et indiquer au besoin ses identifiants de connexion
L’écran suivant vous permet de paramétrer le checkout.
- 18 -
Fig.16 : Panel de sélection des sources à réccupérer.
Sélectionner le répertoire à récupérer en clickant sur « Browse ». Vous accéder à
un panel d’exploration du repository du projet.
Fig.16 : choix des soruces
Si vous êtes intéressé par le développement en cours, sélectionner trunk. Si vous
souhaitez prendre une version stable, parcourez tags (s’il existe).
- 19 -
De retour au panel précédent, vous devez indiquer le répertoire local où déposer
le répertoire choisi. Attention, pensez à créer le répertoire mon_projet car le checkout ne
le créera pas. Vous pouvez laisser les autres options par défaut.
Fig.17 : sélection du répertoire de travail local.
Si le projet est convenablement récupéré (et a été convenablement archivé, c'està-dire en laissant avec les sources, les fichiers propres à NetBeans) NetBeans proposera
de l’ouvrir immédiatement. Vous pourrez alors constater qu’il rend transparent la
structuration propre à Subversion.
- 20 -
Fig.18: Le projet a été correctement checké. NetBeans le reconnaît et propose de l’ouvrir immédiatement.
- 21 -
2.3
LA GESTION DE CONFLIT
Pour illustrer le cas d’un conflit, nous allons supposé que mon_projet contienne
un fichier java nommé ConsoleJPanel.java et que deux utilisateurs travaillent sur ce même
fichier.
Bien qu’ils aient utilisé la version 1.4 du fichier pour travailler, l’utilisateur
Delinchant, travaillant plus vite, a fait et sauvegarder des modifications sur le serveur. La
version locale de « ConsoleJPanel » utilisée par Estrabaut n’est plus synchronisée avec la
version nouvellement archivée par Delinchant. Cette situation est génératrice de conflit
qui selon sa complexité requérra l’intervention de l’utilisateur.
CDICVS
SVN
1.4
CDICVS
SVN
Incrémentation
du numéro
de version
1.5
CadesHelper.java
ConsoleJPanel.java
ConsoleJPanel.java
CadesHelper.java
Commit
1.5
Commited
Numéro de version différent :
conflit
Même numéro
de version :
mise à jour possible
1.4
Delinchant CadesHelper.java
ConsoleJPanel.java
1.4
« Locally Modified »
1.5
CadesHelper.java
ConsoleJPanel.java
CadesHelper.java
ConsoleJPanel.java
1.4
1.4
Error
« Locally Modified »
Estrabaut CadesHelper.java
ConsoleJPanel.java
T = 0 : Les deux utilisateurs
travaillent sur la copie locale
du même fichier
Commit
CadesHelper.java
ConsoleJPanel.java
T =1 : L’utilisateur Delinchant procède
à des modifications et fait un commit
sur le serveur
Fig.19 : Illustration du principe du conflit
- 22 -
T = 2 : L’utilisateur Estrabaut souhaite effectuer
un commit de ses propres modifications.
Il ya conflit
2.3.1 Le conflit simple : résolution par fusion
Le problème du conflit émerge lorsque l’utilisateur Estrabaut souhaite faire un
« Commit » de ses propres modifications. Le « Commit » est refusé par le serveur
Subversion.
Fig.20 : L’utilisateur delinchant et estrabaut ont modifié la même version du fichier. L’utilisateur delinchant a
commuté ses modifications en premier.
- 23 -
Fig.21 : Le commit est refusé par le serveur. Le fichier doit être mis à jour au préalable.
Dans les cas de conflit, il faut effectuer un « Update » du fichier afin que le client
Subversion puisse effectuer une comparaison des versions. Le Menu « Update » se trouve
dans le menu contextuel du fichier (Click-droit puis Subversion et enfin Update).
- 24 Fig.22 : Avant de pouvoir commiter le fichier modifié, il faut le mettre à jour.
Fig.23 : Le fichier une fois mise à jour, contient bien les modifications apportés par les deux utilisateurs.
Dans le cas de version non antinomiques, Subversion effectue seul la fusion
nécessaire. Il copie dans la version locale les éléments additionnels de la version sauvée
sur le serveur.
Un « Commit » est ensuite nécessaire pour valider la fusion des deux fichiers.
L’édition du fichier fusionné permet de constater l’ajout des différentes modifications
faites par les deux utilisateurs.
- 25 -
2.3.2 Le conflit complexe : intervention de l’utilisateur
La gestion des conflits peut s’avérer plus complexe quand les modifications
effectuées par les deux utilisateurs portent sur la même portion de code. Subversion n’est
pas alors compétent pour décider quelles modifications il convient de garder. C’est à
l’utilisateur de trancher.
Admettons que nos deux utilisateurs ont chacun une copie à jour du de la version
1.6 du fichier ConsoleJPanel. Ils modifient chacun de leur côté la même partie du fichier.
Ainsi, une simple fusion ne peut résoudre le conflit.
Fig.24. La même partie du code est modifiée : il y a conflit.
L’utilisateur Delinchant modifie le constructeur d’une classe et archive en premier
ses modifications sur le serveur.
L’utilisateur Estrabaut modifie également le constructeur et souhaite à son tour
sauver ses modifications sur le serveur.
- 26 -
Lors de la demande de « Commit » effectuée par l’utilisateur Estrabaut, celle-ci est
rejetée car CVS rencontre un conflit complexe entre les deux versions. Une fusion de
deux documents ne peut être envisagée pour résoudre le conflit. L’utilisateur qui
rencontre le conflit doit le résoudre lui-même.
Fig.25: NetBeans rend compte du conflit existant en entourant le code conflictuel par des chevrons
NetBeans rend compte du conflit en encadrant par un jeu de chevrons (<<<<<
>>>>>) le passage conflictuel et les portions de code antagonistes.
Une fois le fichier modifié, il suffit d’effectuer un « Commit » pour archiver la
version sur le serveur.
- 27 -
2.3.3 Le « taguage » de version
Admettons maintenant que notre développement arrive à son terme pour ce
projet et que nous considérons avoir atteint une version stable. Nous désirons taguer le
projet en version 1.0 c'est-à-dire faire une photographie du projet à l’instant t et lui
donner comme numéro de version 1.0 et bien sûr archiver le tour sur le serveur.
Dans le menu contextuel cliquez sur « Subversion » puis « Copy to ». Là où CVS
permettait de tagguer fichier par fichier, Subversion propose de faire une copy du projet
dans le répertoire tags contenant les différents versionnement.
Fig. 26 : Taguer un projet revient en fait à en faire une copie dans un répertoire adéquat.
- 28 -
Le panel suivant permet de préciser quelques options importantes à la fonction
de copy.
1
2
3
Fig.27 : Panel de taguage via NetBeans
1 Source : vous avez la possibilité de choisir quelle version taguer : soit une version
archivée sur le serveur soit celle présente dans votre repository local (votre copie de
travail). Soyez vigilants dans votre choix !
2 Option de copie : vous permes de ne pas recopier le répertoire « trunk » mais
seulement son contenu.
3 Destination : assez naturellement, le répertoire de destination est le répertoire « tags »
qui contient donc toutes les versions tagués. Nommer le répertoire final de destination
du nom de la version.
Une fois la copie validée, vous pouvez retrouver les sources archivées via
Subversion dans l’explorateur de code de la forge.
- 29 -