Guide Subversion (niveau 1)

Télécharger des fichiers tout simplement ?

Voici une première partie qui fait office de "guide de survie pour télécharger des fichiers sur un repository subversion sans chercher à savoir ce que c'est". Vous avez besoin de ça si vous souhaitez par exemple, juste récupérer les sources d'un modèle Scenari.

• Téléchargez Tortoise SVN (à moins qu'il n'y ai marqué en très gros sur l'écran de démarrage windows "64 bits edition", c'est la version 32 bits qu'il vous faut : le premier lien avec un nom du genre TortoiseSVN-1.x.x.xxxxx-win32-svn-1.x.x.msi).
• Installez le et redémarrez votre PC.
• Allez dans l'explorateur windows, créez un répertoire vide, et dessus, faites clic droit dessus et "checkout".

• Dans la première zone de texte "URL of repository", copiez-collez l'adresse du "repository subversion" que vous avez trouvé sur la page du projet, ou qui vous a été fournie par le responsable du projet. (exemple pour SCENARIdiscovery : http://scenari-platform.org/svn/demo/trunk/model/ )
• Ne touchez à rien d'autre et cliquez sur "OK".

Voila, si des noms de fichiers défilent, c'est gagné. Bravo !

Lisez la suite si :

• Après quelques jours, vous voulez mettre à jours les fichiers sans tout re-télécharger
• Vous voulez comprendre ce que veulent dire les symboles "point d'exclamation" ou "croix verte" qui apparaissent sur vos répertoires
• Vous utilisez un proxy web qui a bloqué votre connexion
• Vous voulez savoir ce qui fait que subversion est beaucoup plus qu'un simple système de téléchargement de fichiers

Guide Subversion (niveau 2)

Subversion, c'est quoi ?

Subversion est un système de partage de fichiers spécialement conçu pour le travail collaboratif : plusieurs personnes peuvent travailler sur le même projet, voir les mêmes fichiers. Chacun a une copie locale des fichiers du projet, tout le monde communique en se synchronisant avec un serveur grâce aux outils subversion, qui vont calculer et échanger les modifications effectuées entre 2 versions. Le serveur contient l'ensemble de toutes les modifications d'un projet depuis la version 0, ce qui permet de retrouver n'importe laquelle.

Des explications plus approfondies sont présentes dans la documentation officielle de TortoiseSVN : http://tortoisesvn.net/docs/release/TortoiseSVN_fr/index.html

Vocabulaire

• Repository : Tous les fichiers de toutes les versions du projet, sur le serveur
• Working Copy : La version sur laquelle vous êtes en train de travailler sur votre disque dur, avec en plus des fichiers invisibles mais utilisés en interne par les outils subversion (dans des répertoires cachés ".svn")
• Révision : une version des fichiers du projet tels qu'ils sont sur le serveur subversion. Chaque révision a un numéro. La révision la plus récente, celle qui a le plus grand numéro, est appelée HEAD. Le serveur contient tous les ChangeSet et en quelque sorte toutes les révisions qui lui ont déjà été commité. Votre Working Copy contient une seule révision : la dernière avec laquelle à eu lieu une communication entre vous et le serveur (par exemple, celle que vous avez téléchargé par update, ou celle que vous avez créé par commit, voir ci dessous).
• ChangeSet : une collection de modifications sur plusieurs fichiers, qui permettent de passer d'une révision a une autre.

Opérations

• Import : envoi d'un nouveau contenu dans un nouveau répertoire sur le repository
• CheckOut : Récupération du projet sur votre disque dur, à n'utiliser que la première fois
• Update : Mise a jours de vos fichiers, vous obtenez les modifications des autres personnes sans écraser vos changements, vous êtes synchronisé avec la révision du serveur la plus récente
• Commit : Envoi et validations de vos modifications sur le serveur, une nouvelle révision est créée. Vous avez besoin d'un login, d'un mot de passe et des autorisations sur le projet pour pouvoir effectuer un commit. (ou si vous voulez repartir de zéro) (attention : respectez les règles d'exclusions de la partie bonne pratiques)
• Export : Crée une copie propre de votre working copy sans les fichiers cachés ".svn". Pratique si vous souhaitez le redistribuer à des non-utilisateurs de subversion
• Browse : opération spécifique à tortoise qui consiste à afficher une vue du repository (très pratique pour visualiser ou manipuler des répertoires sans tout télécharger)
• Revert : Annule les modifications de votre Working Copy, et rétablit les fichiers tel qu'ils étaient sur le serveur pour la révision que vous utilisez. Attention, les changements que vous avez effectué depuis seront donc perdu.
• Delete, Rename : fait les changements "a la main" dans votre Working Copy pour que subversion puisse garder la trace des mouvements de fichiers. Normalement, c'est la bonne manière de faire les choses, mais avec les programmes SCENARI, ce n'est pas toujours pratique, d'où quelques problèmes lors de certains commits qui chamboulent trop de chose.

Votre compte

• Si vous voulez uniquement effectuer les opération de lecture du repository (CheckOut et Update), vous n'avez pas besoin d'utiliser votre compte
• Si vous voulez effectuer les opérations qui modifient le contenu du repository (Commit), vous devez utiliser votre mot de passe et votre login SVN pour scenari-platform.org

voir : http://scenari-platform.org/trac/scenari/wiki/services pour la gestion des comptes

L'arborescence d'un repository

• chaque repository sur SCENARIplatform est en accès à une adresse du type http://scenari-platform.org/svn/nom_du_projet
• la version la plus récente du projet (celle qui doit être utilisé par défaut) est dans un sous répertoire trunk.
• pour les projets de modélisation, les fichiers qui correspondent a l'atelier SCENARIbuilder sont dans le sous-sous répertoire model

Exemple : pour récupérer la dernière version de l'atelier de simpleslideshow par subversion, utilisez l'adresse suivante : http://scenari-platform.org/svn/simpleslideshow/trunk/model/

• si vous avez terminé une version, vous pouvez créer une version marquée, dans le répertoire "tags" a la place de trunk. Il s'agit de dupliquer l'arborescence, pour figer une version stable, par exemple, vous pourriez copier la bonne révision du trunk dans http://scenari-platform.org/svn/simpleslideshow/tags/1.1/

• si vous souhaitez faire évoluer en parallèle une autre version (par exemple, vous souhaitez faire une version d'un modèle qui utilise des tooltips a la place des fenêtres popup, sans perturber les autres qui travaillent toujours sur la version "fenêtres popup" pour l'instant), vous pouvez créer une copie du trunk dans un sous répertoire branches : http://scenari-platform.org/svn/simpleslideshow/branches/tooltips/

TortoiseSVN

Tortoise est un Client SVN : il se connecte a un repository subversion distant, et gère la synchronisation avec la WorkingCopy. Les opérations sont effectué depuis l'explorateur windows grâce a des changements sur le menu contextuel :

• Téléchargement : http://tortoisesvn.tigris.org/
• Stocker un nouveau modèle sur un nouveau repository
  • Nettoyez votre modèle de tous les fichiers qui ne doivent pas se trouver sur le repository (voir liste dans le chapitre "bonne pratiques" ci-dessous)
  • Exécutez l'opération Import sur le répertoire contenant votre modèle, en destination mettez une adresse du type http://scenari-platform.org/svn/nom-du-projet/trunk/model , votre modèle se trouve maintenant sur le repository du serveur, mais votre contenu local n'a pas été modifié en WorkingCopy et n'est pas géré par subversion

• Vous allez maintenant reprendre ce repository a partir du serveur pour que soit créer votre WorkingCopy. Renomez le répertoire que vous avez ajouté (par exemple nom_du_repertoire-nosvn), puis, utilisez l'opération CheckOut avec des adresses du type :
  • "URL of repository" : http://scenari-platform.org/svn/nom-du-projet/trunk/model
  • "Checkout directory" : C:\Documents and Settings\scenari\Mes documents\SCENARIbuilder ateliers\nom-du-projet

• Ajoutez des fichiers en ignore list : Certains fichiers ne doivent pas être stockés sur le serveur subversions (les fichiers générés ou certains fichiers volumineux de source extérieur)
  • Vous ne pouvez ajoutez des fichiers dans cette liste que si ils sont présent dans votre working copy mais qu'ils ne sont pas géré par tortoise et qu'ils ne sont pas commités sur le serveur.
  • Lancez un Commit, faites un clic droit sur les répertoires a ignorer et choisissez "Add to ignore list", puis exécutez le Commit
  • La liste des fichiers ignorés est gérée par repository, et elle est commune a tous les utilisateurs du même repository, si vous ignorez un fichier, les autres utilisateurs n'auront pas à le faire.

Attention !

Vous devez bien configurer le proxy (menu "settings" -> "network") : Si vous travaillez depuis l'UTC : proxyweb.utc.fr 3128 Si vous travaillez sur votre connexion personnelle (free/wanadoo/autre...) désactivez le proxy Si vous travaillez depuis une autre entreprise et que vous ne savez pas ce que vous devez mettre, essayez sans, essayez avec, contactez votre administrateur système ou demandez moi conseil... Essayez en particulier d'accéder en https si vous avez l'erreur suivante : "Error REPORT request failed on '...' REPORT of '...': 400 Bad Request (http://...)" ), causée par un blocage par le pare-feu.

Sous linux : Kubuntu

• Pour simplement télécharger des sources, il faut aller dans adept manager, et demander l'installation de 2 paquets (http://doc.ubuntu-fr.org/konqueror) :
  • kdesdk-kio-plugins
  • kdesvn-kio-plugins

• Après cela, ouvrez konqueror, tapez :

  svn+nom_de_l_url_sur_laquelle_vous_souhaitez_copier_des_donnees_SVN
  

Exemple :

svn+http://scenari-platform.org/svn/wspderiver/trunk/ pour deriver

• Copiez collez et le tour est joué

Remarque : ça fonctionne aussi bien avec Dolphin (et même on appréciera dans ce cas le mode vue partagée F10)

(source : http://scenari-platform.org/forum/viewtopic.php?p=3481#3481)

Bonnes pratiques

• Fichiers à exclure de la prise en charge de Subversion : dans les paramètres génériques du client subversion (tortoise: 'global ignore pattern', eclipse : 'team/ignored resources') :
  

  *.wsptest .wsptestmeta *.wspexport *.wsprelaxng *.sckit .wspmigr*.log ~gen Thumbs.db *~
  

  • utilisateurs Windows: un fichier de configuration de base de registre (.reg) est disponible ici
  • utilisateurs Linux: vous pouvez ajouter ces patterns à la ligne global-ignores du fichier de configuration ~/.subversion/config

Conseil
En 3.2 vous devez également exclure les éléments suivant : dans le dossier racine et le dossier 'tests' de chaque atelier, ajouter la propriété 'svn:ignore' avec la valeur 'generations'. dans le dossier 'sources' de chaque atelier de test, ajouter la propriété 'svn:ignore' avec la valeur '.wspmeta'.

• Commitez souvent : si jamais vous voulez revenir en arrière, ou récupérer une ancienne version, subversion poura vous aider... a condition que vous n'ayez pas trop trainé pour faire vos commits. Commiter des fichiers sur un serveur est le meilleur moyen de s'assurer qu'ils ne se sont pas perdu s'il vous arrive un malheur en les modifiant sur votre PC. En théorie il est meme conseillé de séparer chaque nouvelle fonctionnalité en un commit différent, en pratique sur SCENARIplatform ce n'est pas une obligation.
• Evitez de commiter si tout est cassé : évitez de commiter des changements qui rendent le projet inutilisable, vérifiez au minimum que ca se lance toujours (pour les modèles, compilation et génération de tests). Dans des petits projets, en début de projet, et si vous travaillez seul, vous avez un peu plus de liberté sur cette règle.
• Mettez des commentaires utiles à vos commits : pas besoin de faire long, mais faites en sorte au minimum que vous puissiez savoir ce que vous avez changé en le relisant. Si les autres arrivent a le comprendre aussi, c'est encore mieux. Si vous avez oublié, vous pouvez le changer après le commit dans la fenêtre des logs.
• Vous devez faire un update avant un commit (sauf si vous êtes le seul qui ai commité sur ce répertoire depuis votre dernier update, ou si vous avez supprimé des fichiers qui risquent d'être ré-ajouté)
• Si vous avez supprimé ou déplacé des répertoires dans les outils SCENARI, il est fort possible que subversion en ai perdu la trace. Subversion peut devenir susceptible, il nécessite normalement que vous lui indiquiez si vous faite disparaitre des répertoires. Pour vous sortir de ce mauvais pas, vous pouvez dans tortoise, soit faire un "browse" pour aller supprimer directement le répertoire sur le serveur, soit refaite un update et marquez comme supprimé le répertoire resurgissant avec la fonction du menu tortoise. Dans les 2 cas, vous devriez pouvoir commiter après cela.
• S'il y a un problème (par exemple, si un commit échoue), n'attendez pas pour le résoudre, sinon ca fera encore plus mal par la suite :)
• Evitez de prêter votre mot de passe, même si plusieurs personnes doivent exploiter le meme projet que vous. Demandez la création d'un compte pour les participants a votre projet, et ajoutez les grâce a l'interface d'administration de SCENARIplatform (utilisez votre identifiant subversion pour vous connecter a cette page).

"Au secours, ca ne marche pas !"

• Vérifiez la configuration du proxy
• Vérifiez quel opération ne marche pas... seulement l'update ? seulement le commit ? echec à l'authentification ?
• Si vous avez fait des choses obscures dans votre répertoire de travail (renomages sans passer par la fonction subversion, inversion de positions de répertoires...), subversion peux perdre la trace de vos fichiers. Votre objectif est alors de retourner dans un état stable, puis de refaire manuellement les opérations qui se sont mal passées.
• Vérifiez si vous arrivez a lire le repository directement dans un navigateur web (cela doit vous afficher une liste de fichiers) : http://scenari-platform.org/svn/sandbox/trunk/
• Vérifiez si le problème concerne uniquement ce repository ou tous les repositorys
• Essayez à partir d'un autre ordinateur, situé sur un autre réseau (par exemple : au bureau et au domicile).
• Contactez stephane.poinsart@utc.fr

Pour aller plus loin

• site officiel de subversion
• site officiel de la documentation de subversion
• site officiel de tortoise SVN, extension au gestionnaire de fichiers windows
• site officiel d'Oxygen, editeur XML avec client Subversion intégré