L’utilisation d’un système de gestion de versions tel que SVN permet de centraliser la gestion des sources pour tous les développeurs et de conserver une trace de toutes les modifications apportées lors des développements.

Cet article présente l’architecture recommandée et les processus à appliquer pour utiliser JCMS avec un serveur SVN.

Note : La plupart de ces recommandations sont également applicables avec CVS.

Pré requis :

• JCMS 6.0 ou JCMS 5.7.5
• Connaissance du processus de déploiement d’une webapp JCMS :
  Cf. Manuel d’installation et d’exploitation
• Notion de base sur la mise en œuvre et l’utilisation d’un serveur SVN
• Installation et utilisation d’Eclipse

1. Principes

1.1 Architecture

Coté serveur :

• 1 serveur SVN pour les développements
• 1 serveur J2EE (e.g Tomcat) pour l’environnement de recette et de pré-production hébergeant la webapp et un Deploy Manager.
• 1 serveur J2EE pour l’environnement de production hébergeant la webapp et un Deploy Manager.

Fig. 1. Architecture

1.2 Mode opératoire

Le processus de développement se décompose en 5 étapes :

1. Configuration initiale
   • Serveur de recette : Installation de la webpp et du Deploy Manager
   • Serveur SVN : Création d’un repository vierge
   • Checkin initial : Récupération de la webapp depuis le Deploy Manager et checkin initiale de la webapp sur le serveur SVN
   • Checkout initial : Récupération de la webapp depuis le SVN
2. Développement
   Synchronisation avec le SVN, puis commit des développements.
3. Recette
   Déploiement des développements sur le serveur de recette et validation.
4. Mise en production
   Déploiement des mises à jour sur le serveur de production.
5. Mise à jour du SVN
   Récupération de la webapp depuis le Deploy Manager et mise à jour du SVN

Fig. 2. Cycle de développement

1.3 Les acteurs et leurs rôles

On distingue trois rôles principaux dans le processus de développement :

• Le mainteneur :
  C’est l’administrateur des développements, il est responsable de l’import initial de la webapp dans le serveur SVN (checkin) et de la mise à jour de l’environnement de recette à partir du serveur SVN (déploiement).
• Les développeurs :
  Ils récupèrent leur environnement de développement sur le serveur SVN (checkout ou synchronisation) et y envoi (commit) leurs modifications.
• L'équipe de recette :
  Ils vérifient que l'application est conforme aux attentes formulées.

Qui fait quoi ?

	Mainteneur	Développeurs	Recette
1. Configuration initiale
Serveur de recette		-	-
Serveur SVN		-	-
Checkin initial		-	-
Checkout initial	-		-
2. Développement	-		-
3. Recette
4. Mise en production		-	-
5. Mise à jour du SVN		-	-

1.4 Gestions des fichiers

1.4.1 store.xml et custom.prop

Les fichiers store.xml et custom.prop évoluent à la fois sur la production et sur les postes développeurs.

Les développeurs sont amenés à créer des données locales (portails, catégories, groupes, contenus, ...) et à utiliser des réglages de propriétés spécifiques. Dans les deux cas, ces données ou propriétés ne doivent pas toujours être envoyés sur la production, donc pas dans le SVN.

Pour résoudre cette problématique, les fichiers store.xml et custom.prop ne sont pas inclus dans le SVN (ceci évite notamment des conflits à chaque synchronisation avec le SVN).
A la place, on entre dans le SVN une version de référence de ces fichiers : store.xml.ref et custom.prop.ref. Il s’agit d’une copie des fichiers originaux issus de la copie de travail.

• Lors du checkin initial, les fichiers de référence sont créés. (cf. 2.4.4 Checkin initial, préparation des fichiers)
• Lors d’un checkout ou d’une synchronisation, le développeur copie ces fichiers de référence vers les fichiers locaux store.xml et custom.prop. (cf. 2.5 Checkout initial)
• Avant un commit, si le développeur souhaite propager ses modifications, il fusionne son store local avec le store de référence (en passant par un l’outil StoreMerge fourni dans JCMS) et peut faire de même avec les propriétés (manuellement). (cf. section 3 Développement)

1.4.2 JSP et classes générés

Les JSP et les classes des types de publication sont régénérés automatiquement par JCMS.
S’ils n’ont pas été modifiés, il n’est pas nécessaire de les inclure dans le SVN.

Pour plus de détails, consultez la section 2.4.4 "Checkin initial, préparation des fichiers".

1.4.3 Autres ressources

Toutes les ressources présentes dans une webapp JCMS ne doivent pas être ajoutées dans le serveur SVN.

Voici quelques règles à connaître pour déterminer les ressources à ignorer:

• Les ressources qui évoluent lorsque que JCMS est lancé ne doivent pas être incluses (logs, stats, lucene). Ces fichiers apparaîtraient conflictuels à chaque synchronisation et seuls ceux du serveur de production sont pertinents.
• Les uploads peuvent être comités ou non…
  En les ajoutant au SVN, les suppressions effectuées sur le serveur de production ne seront plus effectives. En effet les fichiers seront toujours dans le SVN et redéposés lors de la mise en recette.
  En les ignorants, certaines ressources pourraient manquer lors des développements (notamment les images, flash, etc).
  Dans la mesure du possible, il est souhaitable de les ignorer.
• La documentation est ignorée (toutefois, elle peut être incluse pour le besoin des développeurs).
• Les JSP et classes générées sont ignorées.

2. Configuration initiale

2.1 Serveur de recette

Objectif : Installation de la webpp et du Deploy Manager

Installez sur le serveur de recette :

• La toute première version de la webapp
• Le Deploy Manager (DM). Il permettra au mainteneur de récupérer des copies de travail et de déployer les nouvelles versions issues du SVN.

Pour tous les détails d’installation de JCMS, consultez le manuel d’installation et d’exploitation.

2.2 Serveur SVN

Objectif : Création d’un repository SVN vierge

Exemple, sur un serveur Linux.

Pré-requis (à effectuer par l’administrateur de la machine) :

• Présence d’un compte utilisateur "svn" ainsi que d’un groupe du même nom.
  Tous les utilisateurs du SVN (mainteneur et développeurs) devront disposer de ce compte ou d’un compte utilisateur appartenant au groupe "svn".
• Création d’un dossier /home/svn/repositories
  Ce dossier contiendra les repositories SVN.
• Lien symbolique /svn -> /home/svn/repositories
  Ceci permettra de simplifier l’accès aux différents repositories avec les outils de ligne de commande mais également depuis l’environnement Eclipse.

Création d’un nouveau repository "jcms" :

[svn@svn-server~]$ svnadmin create /home/svn/repositories/jcms
[svn@svn-server~]$ svn mkdir file:///svn/jcms/trunk file:///svn/jcms/branches file:///svn/jcms/tags -m "creating initial repository layout"

2.3 Eclipse et SVN

2.3.1 Plugins SVN pour Eclipse

Il existe 2 plugins disponibles pour ajouter le support de SVN dans Eclipse

• Subclipse (édité par Tigris)
  http://subclipse.tigris.org/
• Subversive (édité par Polarion)
  http://www.eclipse.org/subversive/

Nous utiliserons Subsversive qui fourni une interface utilisateur plus ergonomique, notamment lors de la gestion des fichiers à ignorer (svn:ignore).

Installez le plugin Subversive en suivant les indications disponibles sur le site.

http://www.eclipse.org/subversive/

2.3.2 Ajout du repository

Ouvrez la perspective "SVN Repository Exploring"

Dans la vue "SVN Repository", cliquez avec le bouton droit dans la vue et choisissez "New > Repository Location…"

Fig. 3. Ajout du repository

Saisissez l’adresse du serveur SVN (e.g : svn+ssh://localhost/svn/jcms )
Entrez l’utilisateur et le mot de passe pour accéder au serveur SVN (e.g. : dev/dev)

Fig. 4. Propriétés du repository

2.4 Checkin initial

Objectif : Récupération de la webapp depuis le Deploy Manager et checkin initial de la webapp sur le serveur SVN

2.4.1 Récupération d’une copie de travail

Connectez-vous au Deploy Manager et récupèrez une copie de travail.

Décochez tous les fichiers optionnels.

Fig. 5. Récupération d’une copie de travail

2.4.2 Checkout du projet vierge

Ouvrez l’arborescence du repository, on retrouve les 3 dossiers "branches", "tags " et " trunk" créés lors de la création du repository.

Cliquez avec le bouton droit sur le dossier "trunk" et choisissez "Find/Check Out As…"

Fig. 6. Checkout

Choississez l’option "Check out as a project configured using the New Project Wizard".

Puis "Java Project"

Fig. 7. Checkout as Java Project

Entrez un nom de projet (e.g. : JCMS ) et validez.

2.4.3 Import de la copie de travail

Durant cette étape on importe et configure la copie de travail dans Eclipse, cependant on ne la démarrera pas. L’objectif ici est de déposer sur le serveur SVN uniquement les fichiers de la copie de travail avant la génération automatique des classes Java et des JSP par JCMS.

Import dans le projet Eclipse

Décompressez le war de la copie de travail dans un sous dossier " webapp " du projet eclipse.

Note : on place la webapp dans un sous dossier du projet eclipse afin de s’assurer que les ressources générées par Eclipse dans le projet (.classpath, .project, etc) ne feront pas parties de la webapp. Ceci permet également de versionner dans le repository SVN d’autres documents (cdc, docs techniques, etc) sans les faire apparaitre dans la webapp.

Fig. 8. Arborescence du projet

Rafraîchissez la liste des fichiers dans Eclipse en appuyant sur F5.

Configuration du projet Eclipse

En effectuant cette configuration dès maintenant, on s’assure que la configuration sera également envoyée sur le serveur SVN lors du commit initial. Ceci permettra à tous les développeurs d’en bénéficier immédiatement lors de leur premier checkout.

Ouvrez les propriétés du projet Eclipse (clic droit sur JCMS > Properties)

Dans la section "Java Build Path", onglet "Source"

• Supprimez les sources existantes
• Ajoutez le répertoire JCMS/webapp/WEB-INF/classes comme source folder
• Cochez l’option "Allow output folders for source folders"
• Choisissez JCMS/webapp/WEB-INF/classes comme "Default ouput folder"

Fig. 9. Configuration des sources

Dans la section "Java Build Path", onglet "Libraries"
Via le bouton "Add JARs", ajouter toute les librairies de JCMS/webapp/WEB-INF/lib

Fig. 10. Configuration des jars

2.4.4 Préparation des fichiers

Afin d’utiliser JCMS avec un serveur SVN, il faut choisir très précisément les ressources que l’on veut ajouter dans le SVN et celles qu’on veut ignorer.

Pour cela, on utilise une tâche ant depuis Eclipse afin de préparer la webapp avant le commit initiale.

• Assurez-vous d’avoir arrêté Tomcat si vous l’aviez lancé.
• Ignorez les erreurs de compilation engendrées par les suppressions de ressources.
  Note : On supprime des ressources (au lieu de les ignorer) car avec SVN il n’est pas possible d’ignorer des ressources tant que les dossiers dans lesquels elles se trouvent ne sont pas versionnés.

Dans la barre d’outils, ouvrez le menu "Externals Tools" et choisissez "Open External Tools Dialog".

Fig. 11. Open External Tools Dialog

Créez une nouvelle tâche ant utilisant le fichier WEB-INF/jalios/tools/ant-svn.xml

Fig. 12. Tâche ant : ant-svn.xml

Dans l’onglet "Classpath", ajoutez tous les jar de la webapp.

Fig. 13. Tâche ant : Classpath

Dans l’onglet "Targets", cochez uniquement "prepare-initial-commit".

Fig. 14. Tâche ant : Targets

Cette target "prepare-initial-commit" :

• renomme les fichiers store.xml et custom.prop en fichier de références (store.xml.ref et custom.prop.ref)
• efface toutes les ressources de la webapp que l’on considère non pertinente dans une repository SVN (parce qu’il s’agit de fichiers de travail, de fichiers temporaires ou de fichiers qui seront régénérés automatiquement par JCMS, cf section 1.4).
  Si vous souhaitez valider cette liste avant d’effectuez l’opération, vous pouvez utilisez la target "print-files-to-delete".

Attention ! Cette target ne doit être appelée que par le mainteneur avant le commit initial.

Cliquez sur "Run" pour lancer l’opération de préparation de la webapp.

Dans la vue "Navigator", appuyez sur F5 pour rafraîchir les fichiers dans Eclipse.

2.4.5 Commit initial

Ouvrez la perspective "Team Synchronize".

Dans la vue "Synchronize", cliquez sur le bouton "Synchronize".

Fig. 15. Synchronize

Sélectionnez SVN, puis dans la fenêtre suivante, choisissez l’option "Workspace"

Fig. 16. Synchronize : Workspace

Dans la vue "Synchronize", cliquez avec le bouton droit sur le projet JCMS et choisissez "Commit".

Fig. 17. Commit

Sélectionnez toutes les ressources via le bouton "Select All"

2.4.6 Les fichiers à ignorer (svn:ignore)

Avec SVN, la liste des ressources qui ne doivent pas faire parti du SVN est versionnée. Cette liste est spécifique à chaque répertoire, c’est le svn:ignore.

Il suffit que le mainteneur alimente une première fois ces svn:ignore pour que tous les développeurs en bénéficient automatiquement lors de leur checkout.

Checkout de vérification

Effacez complètement le projet dans Eclipse et effectuez un nouveau checkout depuis la vue "SVN Repository".

Démarrage de la webapp

• Copiez les fichiers de référence vers des fichiers de travail locaux
  • Copiez store.xml.ref vers store.xml
  • Copiez custom.prop.ref vers custom.prop
• Démarrez la webapp pour déclencher une génération des fichiers de JCMS.
  La classe custom.JcmsInit référence des classes générées, une exception aura probablement lieu en fin de chargement, vous pouvez ignorer cette erreur.
  Arrêtez Tomcat et passez à l’étape suivante.
• Appuyez sur F5 dans Eclipse pour rafraîchir les fichiers générés dans Eclipse. 

Vous ne devriez maintenant plus avoir d’erreur de compilation et le lancement de JCMS doit se passer correctement.

svn:ignore

Ouvrez la perspective "Team Synchronize"

Vous devriez alors voir un nombre (important) de nouveaux fichiers (jsp générés, classes générées, store.xml, custom.prop, backups, jsynclog, logs, lucene, mashup, jcmsworks, etc).

Ces ressources ne doivent pas faire parti du SVN. Il faut les ignorer.

Pour cela, 2 cas se présentent selon le plugin que vous utilisez :

• Polarion Subversive :
  Sélectionnez en une seule fois l’ensemble des nouveaux fichiers, cliquez avec le bouton droit et choisissez "Add to svn:ignore"
• Tigris Subclipse :
  unitairement sur chaque ressource, cliquez avec le bouton droit sur la ressource et choisissez "Add to svn:ignore".
  Cette étape est longue et fastidieuse car le plugin Subclipse ne permet pas de faire " Add to svn:ignore " sur plusieurs ressources simultanément.

Fig. 18. Add to svn:ignore

Les dossiers parents de ces ressources apparaissent comme modifiés.

Commitez ces modifications

Fig. 19. Add to svn:ignore : commit comment

Le repository est maintenant prêt à être utilisé par les développeurs.

2.5 Checkout initial

Objectif : Configuration d’Eclipse et récupération de la webapp depuis le SVN

2.5.1 Checkout du projet

Ouvrez l’arborescence du repository.

Cliquez avec le bouton droit sur le dossier "trunk" et choisissez "Checkout"

Fig. 20. Checkout

Note : la configuration du projet est automatiquement récupérée lors du checkout. En effet les fichiers .project et .classpath d’Eclipse ont volontairement été inclus dans le SVN lors de l’import initial par le mainteneur. Ainsi Eclipse ne propose pas de choisir le type de projet, et les répertoires des classes et des librairies sont déjà configurés.

2.5.2 Configuration du projet

• Copiez les fichiers de référence vers des fichiers de travail locaux
  • Copiez store.xml.ref vers store.xml
  • Copiez custom.prop.ref vers custom.prop
• Démarrez la webapp pour déclencher une génération des fichiers de JCMS.
  La classe custom.JcmsInit référence des classes générées, une exception aura probablement lieu en fin de chargement, vous pouvez ignorer cette erreur.
  Arrêtez Tomcat et passez à l’étape suivante.
• Appuyez sur F5 dans Eclipse pour rafraîchir les fichiers générés dans Eclipse. 

Vous ne devriez maintenant plus avoir d’erreur de compilation et le lancement de JCMS doit se passer correctement.

3. Développement

Objectif : Synchronisation avec le SVN, puis commit des développements.

3.1 Synchronisation

Avant tout nouveau développement, et avant de commiter vos modifications dans le SVN, synchronisez votre projet avec le SVN. Pour cela :

Ouvrez la perspective "Team Synchronize" puis cliquez sur le bouton "Synchronize".

Fig. 21. Synchronize

Sélectionnez SVN, puis dans la fenêtre suivante, choisissez l’option "Workspace"

Fig. 22. Synchronize : Workspace

3.2 Gestion du store

Deux options se présentent après une synchronisation avec le repository :

3.2.1 Option 1 : Ecraser le store local en le remplaçant par le store de référence du SVN.

Optez pour cette option si vous ne souhaitez pas conserver les données (contenus, portlet, catégories, ...) que vous avez créé dans votre environnement de développement.

Copiez le fichier store.xml.ref vers store.xml.

3.2.2 Option 2 : Fusionner le store local et le store de référence du SVN.

Optez pour cette option si vous avez créé des publications lors de vos développements et que vous souhaitez conserver ces publications tout en récupérant les éventuelles modifications disponibles dans le store de référence.

Effectuez les manipulations suivantes

Ouvrez la perspective Java.

Dans le menu "Run" choisissez "Open Run Dialog…"

Fig. 23. Open Run Dialog

Créez une nouvelle application Java.

Dans l’onglet "Main" spécifiez :

• Votre projet principal (e.g. JCMS) dans le champ project
• com.jalios.jcms.tools.StoreMerge dans le champ main-class
  

  Fig. 24. Run Java Application: StoreMerge

Dans l’onglet "Arguments" spécifiez les arguments suivant :

webapp/WEB-INF/data/store.xml 
webapp/WEB-INF/data/store.xml.ref 
true 

Fig. 25. Run Java Application: StoreMerge Arguments

Cliquez sur "Run" pour lancer la fusion.

Si une fusion doit être effectuée, StoreMerge effectue les opérations suivantes :

• Une copie de sauvegarde du store local est effectuée.
• Le store de référence étant déjà dans le SVN, aucune sauvegarde n’est effectuée pour ce fichier.
• Les opérations JStore des deux stores sont fusionnées dans un nouveau store qui vient écraser le store.xml et le store.xml.ref.

Voici les scénarios possibles et les actions que vous pouvez/devez effectuer par la suite.

a. Les deux stores sont identiques :

INFO- current store: webapp/WEB-INF/data/store.xml
INFO - ref store    : webapp/WEB-INF/data/store.xml.ref
INFO - Start merging...
INFO - Compute store diff
WARN - No diff. Stop merge.
INFO - The stores have not been changed (status: No Diff).

Les fichiers ne sont pas modifiés.

→ Vous pouvez commiter vos autres développements.

b. Le store local a été modifié, le store de référence n’a pas évolué :

INFO - current store: webapp/WEB-INF/data/store.xml 
INFO - ref store    : webapp/WEB-INF/data/store.xml.ref
INFO - Start merging...
INFO - Compute store diff
INFO - upgrade the store
INFO - compute the new suffix
INFO - Copy the newSuffix in refStore from deploy_5000
INFO - Merge done.
INFO - Override the ref store
INFO - Backup the current store: webapp/WEB-INF/data/store.xml-1234567890123.bak
INFO - Copy the new ref store as the current store
INFO - end merging.

Le store.xml.ref est remplacé par le store.xml local.

→ Vous pouvez commiter le nouveau store.xml.ref et vos autres développements.

c. Le store de référence à été modifié, le store local n’a pas évolué :

INFO - current store: webapp/WEB-INF/data/store.xml
INFO - ref store    : webapp/WEB-INF/data/store.xml.ref
INFO - Start merging...
INFO - Compute store diff
INFO - upgrade the store
INFO - compute the new suffix
INFO - Copy the newSuffix in refStore from deploy_5000
INFO - Merge done.
INFO - Override the ref store
INFO - Backup the current store: webapp/WEB-INF/data/store.xml-1234567890123.bak
INFO - Copy the new ref store as the current store
INFO - end merging.

Le store.xml local est remplacé par le store.xml.ref.

→ Démarrez votre webapp avec le nouveau store de référence pour valider que vos développements fonctionnent avec ce nouveau store.
Vous pouvez commiter vos autres développements.

d. Les deux stores ont évolués et il n’y aucune opération conflictuelle

INFO - current store: webapp/WEB-INF/data/store.xml
INFO - ref store    : webapp/WEB-INF/data/store.xml.ref
INFO - Start merging...
INFO - Compute store diff
INFO - upgrade the store
INFO - compute the new suffix
INFO - Copy the newSuffix in refStore from deploy_5000
INFO - Merge done.
INFO - Override the ref store
INFO - Backup the current store: webapp/WEB-INF/data/store.xml-1234567890123.bak
INFO - Copy the new ref store as the current store
INFO - end merging.

Les deux stores sont fusionnés dans un nouveau store qui vient écraser le store.xml et le store.xml.ref.

→ Démarrez votre webapp avec le nouveau store pour valider la fusion et pour valider que vos développements fonctionnent avec ce nouveau store.
Vous pouvez commiter le nouveau store.xml.ref et vos autres développements.

e. Les deux stores ont évolués et certaines opérations sont conflictuelles

INFO - current store: webapp/WEB-INF/data/store.xml
INFO - ref store    : webapp/WEB-INF/data/store.xml.ref
INFO - Start merging...
INFO - Compute store diff
WARN - Conflict update/update on data 'j_300'
INFO - upgrade the store
INFO - compute the new suffix
INFO - Copy the newSuffix in refStore from deploy_5000
INFO - Merge done.
INFO - Override the ref store
INFO - Backup the current store: webapp/WEB-INF/data/store.xml-1234567890123.bak
INFO - Copy the new ref store as the current store
INFO - end merging.

Un ou plusieurs conflits ont été détectés.
Les deux stores sont fusionnés dans un nouveau store qui vient écraser le store.xml et le store.xml.ref.

→ Démarrez la webapp avec le nouveau store.
Lancez un contrôle d’intégrité pour valider la fusion.
Pour les conflits de type update/update, vérifiez l’état des données concernées dans le nouveau store. Vous pouvez consulter l’historique pour avoir le détail des changements.
Vous pouvez commiter le nouveau store.xml.ref et vos autres développements.

3.3 Gestion du fichier custom.prop

Si votre fichier custom.prop contient des modifications à reporter dans le SVN (pour tous les développeurs), fusionnez manuellement votre fichier custom.prop et le fichier custom.prop.ref. Sélectionnez au cas par cas les propriétés à récupérer.

4. Recette

Objectif : Déploiement des développements sur le serveur de recette et validation.

Lorsqu’un les développements sont terminés, en tant que mainteneur effectuez les opérations suivantes :

• Gelez les commits des développeurs (éventuellement via un lock sur le SVN)
• Synchronisez votre environnement avec le SVN.
• Ouvrez le Manuel d’installation et d’exploitation , section 8 "Procédure de Mise à jour et de déploiement".
  Suivez les étapes 3, 4 et 5 avec votre webapp locale et l’environnement de test :
  • Etape 3 : Calcul des changements
  • Etape 4 et 5 : Validation en zone de pré-production
• Demandez aux équipes de recette de validez vos développements.
• Attendez les retours de bugs, corrigez-les et recommencez.

5. Mise en production

Objectif : Déploiement de la webapp de recette sur le serveur de production

Ouvrez le Manuel d’installation et d’exploitation, section 8 "Procédure de Mise à jour et de déploiement ".
Suivez l’étape 6 : "Mise à jour de la production".

6. Mise à jour du SVN

Objectif : Récupération de la dernière version de webapp de production depuis le Deploy Manager et mise à jour du SVN à partir de cette webapp.

• Téléchargez une copie de travail de la webapp de recette depuis le Deploy Manager.
• Décompressez cette copie de travail dans votre workspace Eclipse (assurez vous de ne plus avoir aucun développement en cours).
• Rafraichissez les ressources dans Eclipse (F5)
  Note : Si des workflows ont été supprimés en production, vous devez reproduire manuellement la supression de ces derniers dans le workspace Eclipse.
• Copiez store.xml vers store.xml.ref
• Copiez custom.prop vers custom.prop.ref
• Effectuez une synchronisation avec le SVN
  Les fichiers de référence devraient apparaitre modifiés, ainsi que de nouvelles signatures de la webapp
• Committez les modifications