|
Ce document décrit une première prise en main de subversion dans le projet esup-portail. Il donne des recommandations pour la 'publication' des sources vers l'espace subversion sans aborder les fonctionnalités avancées. Un exemple de développement de canaux servira de support à ce document ; le client subclipse intégré dans eclipse servira de support à ce document. |
| Dates de modification | ||
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Un excellent client subversion sous Windows : tortoiseSVN.
Conseillé d'utilisation au moins lors de vos premiers tests, il est assez simple de prise en main.
Note
On utilisera souvent le terme 'SVN' pour décrire le protocole subversion. En fait, svn est également le nom du client ligne de commande de subversion.
Les répertoires, renommages et les propriétés des fichiers sont versionnés. Il est maintenant possible de supprimer un répertoire.
Les numéros de révision ne sont plus sur les fichiers individuellement mais sur le dépôt lui-même.
Webdav est utilisé comme protocole réseau, apache V2 comme serveur support. Ceci permet de passer simplement les firewall, d'accéder aux informations en lecture directement avec un navigateur web en http ou https, et d'utiliser les mécanismes d'authentification apache (LDAP par exemple). Il est également possible d'assurer une protection des échanges et en particulier du mot de passe en utilisant webdav dans https.
Les branches et les tags sont assimilés à des opérations de "copie", la manipulation est donc très simple. Les copies subversion sont virtuelles, les branches et tags au niveau du dépôt ne sont que des références à des révisions de documents / répertoires.
Le dépôt subversion ne devrait contenir strictement que les fichiers nécessaires à la compilation puis l'utilisation du sous-projet.
Par exemple, les sources , docs, fichiers de propriété génériques, ...
Et pas les classes compilées, pas les fichiers liés à l'environnement eclipse, ....
Donc, si la source du dépôt SVN est un projet eclipse, supprimer les fichiers commençant par '.' (ex : .project), le répertoire build, tous les fichiers qui n'ont pas à se trouver dans le package final et qui risque de gêner d'autres développeurs participants au projet.
En ce qui concerne le fichier build.properties : il est probable qu'il soit lié à votre propre environnement. Dans ce cas, créez dans le sous-projet un fichier build.example.properties avec des définitions par défaut, mettez ce fichier dans le dépot, et n'incluez pas votre propre fichier build.properties.
Penser à mettre un commentaire à chaque commit. Cela va faciliter les éventuels retour en arrière, merge, ... dans le dépôt subversion.
A remarquer qu'un projet subversion est constitué de 3 répertoires principaux :
C'est le répertoire de travail. C'est dans ce répertoire qu'on contruit normalement le projet. Donc, sauf cas exceptionnels (modifications dans une branche), on travaillera toujours dans le répertoire trunk du projet.
C'est le répertoire qui contiendra les versions 'taguées'.
C'est le répertoire qui contiendra les éventuelles branches du projet.
A noter qu'on ne travaillera jamais dans l'arborescence 'tags'.
Important
Il faut systématiquement poser un tag lors du dépôt d'une nouvelle version packagée du sous-projet dans l'espace de téléchargement. Ce tag doit nécessairement refléter la version du sous-projet (ex : 1.0-RC1).
Le projet esup-portail est hébergé par le CRU, comme un projet sourcesup.
Chaque 'canal' ou sous-composant esup-portail est ou sera hébergé comme un projet sourcesup à part entière. Sourcesup propose aux projets hébergés le SCV subversion.
Dans les paragraphes à venir, nous allons traiter le cas de la création puis des différentes modifications d'un canal : CMonCanal.
Le nom du projet sourcesup sera esup-CMonCanal ; les urls d'accès au dépôt subversion du projet sera :
Il est plus que conseillé d'utiliser https pour tout accès en écriture, depuis les clients SVN, afin de protéger le mot de passe.
Les exemples suivants n'ont pas été réalisés avec le serveur subversion du CRU, mais sur un serveur de test ; l'url d'accès à ce serveur (https://subversion.univ-nancy2.fr:8443/esup-CMonCanal) est donc différente de l'URL réelle du projet esup-portail.
Comme indiqué, les exemples s'appuieront sur le client subclipse, dans l'environnement eclipse ; on suppose que le plugin subclipse est déja installé.
Note
Il est intéressant, pour une première prise en main, d'installer également le client tortoiseSVN sur sa machine, de faire un 'checkout' du sous-projet dans un autre répertoire, puis de faire régulièrement des 'update', afin de voir le résultat des différentes commandes.
Il est également possible de suivre les changements à l'aide d'un navigateur W3.
On suppose que les sources initiales du projets sont dans C:\esup\CMoncanal. Le projet n'est pas encore connu de subversion.
On va ici se situer dans le développement d'un canal esup-portail ; les vues décrites concernent la perspective 'java'. Il es possible d'avoir plus d'informations depuis éclipse en switchant vers la perspective 'SVN Repository' ; en particulier, il sera possible d'explorer les diférents tags, branches, ...
On suppose que le projet subversion esup-CMonCanal est déja créé.
On va créer les sous-répertoires tags et branches.
On ne créera pas le sous-répertoire 'trunk' ; c'est spécifique à subclipse, qui veut créer le répertoire de dépot par défaut lors de la création du projet.
svn mkdir https://subversion.univ-nancy2.fr:8443/esup-CMonCanal/tags \ https://subversion.univ-nancy2.fr:8443/esup-CMonCanal/branches \ -m "création des arborescences de premier niveau du sous-projet CMonCanal"
Si vous désirez le faire avec eclipse
ouvrir la perspective 'SVN Repository'
Dans la 'fenêtre' SVN Repository, faire clic droit, New, Repository Location
Url : saisir https://subversion.univ-nancy2.fr:8443/esup-CMonCanal
Saisir son login / password
La 'location subversion' https://subversion.univ-nancy2.fr:8443/esup s'afiche alors dans la fenêtre SVN Repository
Clic droit sur la location : - New - New Remote Folder ; Dans la fenêtre "New Remote Folder", le champ 'Folder Name', saisir : "tags" ; entrez un commentaire, puis valider.
Appliquer la même procédure pour créer le répertoire branches.
Voici une copie d'écran de l'explorer SVN Repository suite à ces actions.
Note
La création des arborescences tags et branches peut se faire ultérieurement, lorsque le besoin s'en fait sentir.
Depuis la perspective eclipse java, depuis la racine du projet CMonCanal, faire clic droit, puis team, puis 'Share project'. Si le plugin CVS est également installé, il faudra faire le choix SVN.
Choisir "Create a new repository location", puis :
Url : https://subversion.univ-nancy2.fr:8443/esup-CMonCanal
Voir la copie d'écran.
Cliquer sur Next ; choisir "Use specific folder name" et indiquer 'trunk' comme 'folder name'.
Voir la copie d'écran.
Note
Pour information, les commandes svn générées par subclipse lors de ces opérations sont les suivantes :
mkdir -m "Initial import." https://subversion.univ-nancy2.fr:8443/esup-CMonCanal/trunk checkout -N -r HEAD https://subversion.univ-nancy2.fr:8443/esup-CMonCanal/trunk
Noter que la racine du projet, dans le 'Package Explorer' eclipse, est maintenant nommée CMonCanal[trunk].
Ensuite, choisir les fichiers qui doivent être déposés dans le serveur subversion. On va d'abord tout sélectionner (Select all), puis supprimer de la sélection les fichiers et répertoires qui ne doivent pas être présents dans le dépot : répertoire build, fichiers '.*', fichier build.properties, ...
Metre un commentaire de modification.
Voir la copie d'écran.
Note
Pour information, eclipse génère à cette occasion une série de commande 'add', pour chaque fichier/répertoire ajoutés au dépôt, suivi d'un commit de chacun de ces fichiers/répertoires.
Vous pouvez contrôler la publication de vos fichiers à l'aide de tortoiseSVN, ou d'un simple navigateur web.
Conseil
Pour supprimer globalement dans eclipse le dépôt de certains fichiers (ex: .classpath, .project, ...) vers subversion ou CVS lors des commit :
Windows - Préférences - Team - Ignored Resources . Ajouter les patterns de fichiers à exclure.
Le ou les développeurs va faire évoluer les sources. Au fur et à mesure du développement, lorsque le développeur estime avoir fait des modifications locales 'à priori' assez stables, il va 'commiter' vers le dépôt.
Depuis la racine du projet CMonCanal, clic droit, Team, Commit ; saisir un commentaire.
Si plusieurs développeurs travaillent sur le même sous-projet, penser à mettre à jour très souvent votre copie locale :
Depuis la racine du projet CMonCanal, clic droit, Team, update
Après avoir 'finalisé' une première version du sous-projet, il va être temps d'en produire une première 'Release Candidate' : la 1.0-RC1.
Toute version mise dans l'espace de download doit nécessairement être taguée.
Pensez à commiter le projet avant d'exécuter les actions suivantes.
Voici la procédure avec subclipse :
Depuis la racine du projet CMonCanal, clic droit, Team, Branch/Tag :
From https://subversion.univ-nancy2.fr:8443/esup-CMonCanal/trunk
To https://subversion.univ-nancy2.fr:8443/esup-CMonCanal/tags/1.0-RC1
Mettre un commentaire de commit
Voir la copie d'écran.
Contrôler par curiosité depuis un navigateur web, ou tortoiseSVN.
Note
Pour information, la commande svn générée par subclipse :
copy -rHEAD https://subversion.univ-nancy2.fr:8443/esup-CMonCanal/trunk \ https://subversion.univ-nancy2.fr:8443/esup-CMonCanal/tags/1.0-RC1
En remarque, cete 'copie' logique n'a pas donné lieu à copie physique des différents fichiers ; ce sont des références qui ont été ajoutées dans une base de données.
On peut ensuite ré-itérer le processus des deux paragraphes précédents.
Il sera ensuite facile de revenir aux sources ayant donné lieu à publication dans l'espace de téléchargement du projet esup-portail.
On suppose maintenant qu'une version 1.0 'finale' a été publiée. Elle aura donné lieu bien sûr à un tag 1.0.
Une release majeure signifie de nouvelles fonctionnalités à apporter au sous-projet.
Le ou les programmeurs vont maintenant apporter les modifications nécessaires à ces fonctionalités, et à les commiter régulièrement. Ceci va toujours se faire dans le répertoire trunk.
Ca va donner lieu éventuellement à des tags 2.0.RC-x .
On suppose qu'ici, un bug vient d'être remonté, qui concerne la version 1.0. Il faut donc pouvoir revenir à cette version, appliquer une correction, et faire évoluer la 1.0 en 1.1, sans impacter la 2.0.xx.
On va crer une branche "version 1" qui va être issue de la dernière version 1.x (ici, 1.0), et dans laquelle on va pouvoir apporter des modifications concernant les versions 1.x, sans impacter la branche principale.
Avec un client svn 'normal', la manipulation se fait en une passe :
svn copy https://subversion.univ-nancy2.fr:8443/esup-CMonCanal/tags/1.0 \ https://subversion.univ-nancy2.fr:8443/esup-CMonCanal/branches/1 \ -m "creation branche 1"
Avec subclipse, c'est un peu plus compliqué.
A priori, 2 méthodes : depuis la perspective java, ou depuis la perspective 'SVN Repository'.
Depuis la perspective java, subclipse ne sait faire de copie que depuis le 'source' courant ; on va procéder en 2 étapes : utiliser le tag 1.0 comme source courant, puis copier vers la branche 1.
(il aurait été plus simple de créer la branche 1 dès le tag 1.0, mais on peut parier que personne n'y pense à ce moment).
On va maintenant utiliser la branche tags/1.0 comme source courant, de manière temporaire.
Racine du projet CMonCanal, clic droit, Team, Switch.
Champ toUrl, choisir https://subversion.univ-nancy2.fr:8443/esup-CMonCanal/tags/1.0
Note 1
pour info, la commande svn générée par subclipse :
switch https://subversion.univ-nancy2.fr:8443/esup-CMonCanal/tags/1.0 C:/eSup/CMonCanal -rHEAD
On remarque que la racine du projet, dans le 'Package Explorer' eclipse, est maintenant nommée CMonCanal[tags/1.0].
Note 2
La commande switch permet également de revenir facilement à une révision quelconque.
Important
Ne rien modifier dans tags/1.0. On ne modifie jamais quoi que ce soit dans la branche tags.
On procède comme pour la création d'un tag :
Depuis la racine du projet CMonCanal, clic droit, Team, Branch/Tag :
From https://subversion.univ-nancy2.fr:8443/esup-CMonCanal/tags/1.0
To https://subversion.univ-nancy2.fr:8443/esup-CMonCanal/branches/1
Mettre un commentaire de commit
Note
Pour info, la commande svn générée par subclipse :
copy -rHEAD https://subversion.univ-nancy2.fr:8443/esup-CMonCanal/tags/1.0 \ https://subversion.univ-nancy2.fr:8443/esup-CMonCanal/branches/1
Pour 'le fun', controler avec tortoiseSVN ou un navigateur web.
Se positionner sur esup-CMonCanal/tags/1.0 ; Clic droit - Copy
Puis, se positionner sur esup-CMonCanal/branches ; Clic droit - Paste ; ajouter un commentaire
Enfin, se positionner sur esup-CMonCanal/branches/1; Clic droit ; Rename / Move ; renommer 1.0 en 1
Note
Pour info, la commande svn générée par subclipse lors du 'Paste' :
copy -rHEAD https://subversion.univ-nancy2.fr:8443/esup-CMonCanal/tags/1.0 \ https://subversion.univ-nancy2.fr:8443/esup-CMonCanal/branches
Pour 'le fun', controler avec tortoiseSVN ou un navigateur web.
Depuis la perspective java.
Pour appliquer le patch, il va falloir 'switcher' vers la branche 1 :
Racine du projet CMonCanal, clic droit, Team, Switch.
Champ toUrl, choisir https://subversion.univ-nancy2.fr:8443/esup-CMonCanal/branches/1
Vérifier que le nom du projet devient CMonCanal[branches/1]
Appliquer les modifications. Commiter.
On suppose maintenant que ce patch doit également s'appliquer à la branche principale.
Voici la procédure :
passer trunk en version courante (switch) ; le nom du projet doit redevenir CMonCanal[trunk].
Racine du projet CMonCanal, clic droit, Team, Merge.
https://subversion.univ-nancy2.fr:8443/esup-CMonCanal/branches/1
Chosiri la révision dans l'historique. Si je chosisi la révision 11, la révision 10 s'affiche dans From:, et 11 dans To: .
Maintenir coché "Use From URL" ; Choisir révision 11.
Voir copie d'écran.
Controler : Team, 'Show pending operations'. Si OK, commiter la (les) modification(s) ; mettre un commentaire parlant :
"Merged revisions 10:11 of CMonCanal/branches/1 to /trunk"
Note 1
pour info, la commande svn générée par subclipse :
merge -r10:11 https://subversion.univ-nancy2.fr:8443/esup-CMonCanal/branches/1 C:/eSup/CMonCanal
Note 2
La commande merge applique les changements désirés dans le file système local. Il faut donc ensuite commiter pour l'appliquer dans le dépôt subversion.
En mode ligne de commande, il aurait suffit de faire un simple checkout de https://subversion.univ-nancy2.fr:8443/esup-CMonCanal/trunk.
Avec subclipse, il faut appliquer la procédure suivante :
Ouvrir la perspective 'SVN Repository'
Clic droit ; new ; Repository Location
Url : https://subversion.univ-nancy2.fr:8443/esup/CMonCanal/trunk
Dans la fenêtre 'SVN Repository" :
clic droit sur le repository "https://subversion.univ-nancy2.fr:8443/esup-CMonCanal/trunk"
"Check out As ..." ; Choisir "Java Project" ; nommer le projet (CMonCanal, par exemple). Ne pas tenter de modifier les caractéristiques du projet à ce moment : valider 'tel quel' (tant que les fichiers ne sont pas rapatriés - checkout - il n'est pas possible de définir les propriétés du projet).
Un check-out est alors effectué ; les fichiers de la version de développement (trunk) de CMonCanal sont alors recopiés dans un nouveau projet local eclipse, lié au repository.
Dans le "package explorer", le projet est alors nommé "CMonCanal[https://subversion.univ-nancy2.fr:8443/esup-CMonCanal/trunk]". Il va falloir maintenant le paramétrer comme d'habitude :
Propriété du projet - "Java Build Path"
Source : Retirer le source "CMonCanal" ; Puis, faire add folder, et choisir CMonCanal/source
Default ouput folder : choisir CMonCanal/build (le créer s'il n'existe pas).
libraries : ajouter les librairies nécessaires : Add External Jars .
S'assurer que le projet compile bien. Vous pouvez maintenant travailler sur le projet, commiter, ... en fonction de vos droits sur le dépôt subversion.
Ceci concerne la création de packages zippés, à mettre dans l'espace de téléchargement du projet esup : il est conseillé de les réaliser à partir de copie svn depuis la branche 'tags' correspondante : ceci permet de s'assurer du synchronisme entre les 2 ; ça permet également d'éviter que des fichiers de travail (.project, par exemple), ne se retrouvent dans le package mis à disposition.
Dans cet exemple, nous avons choisi d'utiliser le répertoire trunk comme répertoire de développement, même lors du passage à une version majeure (ici, la version 2).
C'est la procédure qui paraît le plus simple pour des projets de taille moyenne, et c'est ce qui est décrit dans le tutorial subversion.
Dans le cas de gros projets, où le passage d'une version majeure à la suivante donne lieu à des modifications très importantes, et risque de se prolonger sur une période longue (comme par exemple, uPortal de la version 2 vers la version 3), il peut être préférable de créer une branche dédiée à la nouvelle version.
Des développeurs peuvent alors continuer à faire vivre le projet ancienne version, dans l'arborescence trunk, alors que d'autres travaillent directement dans la branche correspondant à la nouvelle version majeure.
Le checkout sert en particulier à récupérer la première fois le contenu d'un dépôt subversion.
Comme indiqué auparavant, la création d'un tag ou d'une branche se fait sans duplication des fichiers côté serveur.
Par contre, côté client SVN (On parle ici client banalisé, hors éclipse), il faut être prudent sur la manière de spécifier la branche du checkout. Ainsi, si on prend l'exemple précédent :
svn co https://subversion.univ-nancy2.fr:8443/esup/CMonCanal/trunk CMonCanal : récupération de la branche de développement du canal CMoncanal
svn co https://subversion.univ-nancy2.fr:8443/esup/CMonCanal CMonCanal : récupération des 3 branches du canal CMoncanal : trunk, tags, et branches.
Si 20 tags et 3 branches contenant chacune 5 tags ont été créés, on va ainsi récupérer coté client 36 occurences du projet !
svn co https://subversion.univ-nancy2.fr:8443/esup esup : Oups ! on multiplie le cas précédent par le nombre de sous-projets du projet esup !
subclipse parait bien utile pour des projets développés dans l'environnement eclipse.
A noter que pour toute intervention au niveau repository subversion en dehors du projet, il faut utiliser la perspective 'SVN Repository'.
Pour d'autres projets, ou pour un usage avancé des fonctionnalités de subversion, il est conseillé d'utiliser d'autres clients svn qui seront plus souples d'utilisation.
subclipse n'offre pas d'aide en ligne. Vous pouvez utiliser l'aide de tortoiseSVN, elle s'applique très souvent aux fonctions de subclipse, les écrans étant souvent similaires.
