Suivez les évolutions de vos documents avec SVN25 min read

Il est important de suivre les évolutions de tous les documents d’un projet, afin que tous les intervenants soient bien synchronisés. Dans cet article nous allons voir comment des outils dédiés au code, tels que SVN, peuvent être utilisés à cette fin.

Cet article est un peu long car il présente dans une première partie le principe de la gestion de configuration, puis dans une seconde partie il devient un tutoriel pour l’utilisation de SVN appliqué à la gestion de documents de projet.

La gestion de configuration

Nous avons déjà parlé de l’utilité de garder un suivi des évolutions d’un document dans un précédent article sur leur organisation. Les outils de suivi des modifications proposés par la suite office de Microsoft sont plutôt pratiques pour ça, si chaque utilisateur pense bien à les activer.

Cependant, dans un projet il est bien rare de n’avoir qu’un seul document. Comme nous l’avons vu, les documents sont liés entre eux. Un document de tests dépend d’un document de spécifications, qui lui-même dépend d’un cahier des charges, par exemple.

Nous avons également vu que lorsqu’un document évolue, il faut mettre à jour les documents qui en dépendent. Donc si mon client me livre une version 2 de son cahier des charges, mon document de spécification initial n’y réponds plus. Je vais devoir le faire évoluer en version 2, et par le même mécanisme le document de tests devra évoluer également.

On obtient donc deux configurations. La première contient les documents en version 1, et la seconde en version 2. Ce qu’on appelle la gestion de configuration est donc ce qui permet d’associer différentes versions de différents documents entre eux. C’est ce qui permet de retrouver l’état de tous les documents d’un projet à un instant T de ce projet.

Bien sûr, certains documents peuvent ne pas évoluer entre deux versions de la configuration. Par exemple, nous pourrions avoir un documents de normes en entrée (une norme ISO par exemple), à appliquer sur les documents du projet, et qui n’évolue que très rarement.

On peut également avoir des documents qui apparaissent dans une version de la configuration, mais qui n’étaient pas présents dans les versions précédentes. Si le projet se complexifie, par exemple, et qu’on décide de diviser le document de spécifications en deux documents distincts.

Configuration 1

3 documents
Configuration 2

5 documents dont 2 nouveaux
Configuration 3

5 Documents
Cahier des charges V1Cahier des charges V2Cahier des charges V3
Spécifications fonctionnelles V1Spécifications fonctionnelles V2Spécifications fonctionnelles V3
Spécifications matérielles V1Spécifications matérielles V2
Spécifications logicielles V1Spécifications logicielles V2
Normes Environnementales V3Normes Environnementales V3Normes Environnementales V3
Exemple de d’évolution des configurations d’un projet

On peut sans problème avoir des documents dont le numéro de version est différent de celui de la configuration. La configuration permet justement de grouper ensemble une version de chaque document pour figer un état particulier et cohérent du projet.

SVN pour la gestion de configuration documentaire

Le marché regorge d’outils de gestion documentaire (GED) que vous connaissez peut-être. Pour de grandes entreprises qui doivent gérer des dizaines, des centaines de milliers de documents, ces outils qui proposent une multitude de fonctionnalités sont certainement la meilleure solution.

Dans cet article, nous vous proposons une solution qui peut être mise en place rapidement et qui s’intègre directement à l’explorateur Windows. Il existe une solution équivalente pour Linux, laissez nous un message en commentaire si ça vous intéresse d’avoir un tuto sur le sujet !

Cette solution utilise un outil bien connu du monde du développement logiciel il y a quelques années : SVN (Apache Subversion est son nom complet).

Logo SVN
Logo SVN

Pour les softeux qui liraient cet article et qui se demanderaient pourquoi ne pas utiliser Git, qui est quand même vachement plus à la mode en ce moment, je dirais qu’il ne faut pas uniquement se fier à sa popularité pour choisir un outil. Le principale avantage de Git, pour les développeurs, est qu’il est décentralisé. C’est à dire, pour simplifier un max, qu’il n’est pas obligé d’avoir une connexion internet en permanence pour l’utiliser. Mais cela fonctionne bien parce que les fichiers que manipulent les développeurs de logiciels sont des fichiers texte tout simples, sans mise en forme, qu’il est facile de fusionner. Les fichiers de documentation sont souvent des fichiers Word, PDF, Excel, PowerPoint… qu’il est quasi impossible de fusionner automatiquement. Nous allons devoir verrouiller les fichiers que nous modifions, et cela est très compliqué sur un système décentralisé comme Git. Fin de la parenthèse !

SVN est un outil de gestion de configuration créé au début des années 2000 pour succéder à CVS. C’est un système centralisé, c’est à dire qu’il fonctionne sur un schéma client-serveur. Chaque client (utilisateur, rédacteur d’un document) possède sur son ordinateur des documents qui sont synchronisés sur un serveur. Les modifications apportées à un document par un utilisateur sont ensuite “livrées” sur le serveur afin que les autres utilisateurs puissent récupérer la nouvelle version de ce document. Le serveur SVN agit ainsi comme une “source de vérité” qui permet à tous les acteurs d’un projet de partager des documents toujours à jour.

Installer SVN et faire sa première livraison

Rien de tel que la pratique pour comprendre comment SVN peut être utilisé pour partager un ensemble de documents et gérer des versions et des configurations.

Installer TortoiseSVN

TortoiseSVN est un logiciel client pour SVN. Il a l’avantage de très bien s’intégrer à l’explorateur Windows. SVN est donc la technologie de gestion de version, TortoiseSVN est un outil logiciel qui vous permet d’utiliser SVN sur votre PC.

Commençons par aller télécharger sa dernière version. Vous la trouverez ici : https://tortoisesvn.net/downloads.html. A l’heure où est écrit cet article, c’est la version 1.14.0. Cliquez sur le bouton correspondant à votre système (32 bits ou 64 bits) ; le téléchargement devrait commencer.

Exécutez ensuite le ficher téléchargé (dans mon cas il est nommé TortoiseSVN-1.14.0.28885-x64-svn-1.14.0.msi). Faites “Next” à toutes les étapes :

Les outils TortoiseSVN devraient être apparues dans votre menu “démarrer” :

TortoiseSVN dans le menu "démarrer"
TortoiseSVN dans le menu “démarrer”

Et également dans votre menu contextuel de l’explorateur de fichiers (clic droit dans l’explorateur de fichiers) :

TortoiseSVN dans le menu contextuel de l’explorateur de fichiers Windows
TortoiseSVN dans le menu contextuel de l’explorateur de fichiers Windows

Créer un dépôt sur RiouxSVN

Vous vous souvenez que SVN fonctionne selon une architecture client-serveur. Nous venons d’installer le client sur notre ordinateur. Il est temps de créer un dépôt sur un serveur. Nous appelons “dépôt” la “source de vérité” présente sur le serveur.

Pour cette démonstration, nous allons utiliser un service en ligne gratuit d’hébergement de dépôt SVN. Rendez-vous sur le site RiouxSVN et créez-y un compte (Sign up).

Une fois le compte créé, rendez-vous sur votre explorateur de dépôts (repositories en anglais) https://riouxsvn.com/repositories/ et cliquez sur le bouton “Create new repository…” pour créer un nouveau dépôt.

RiouxSVN - Créer un nouveau dépôt 1/6
RiouxSVN – Créer un nouveau dépôt 1/6

Donnez-lui un titre et un nom. Le titre est libre. Le nom ne doit comporter que des minuscules et aucun espace. Je ne suis pas le créateur de RiouxSVN. ne me demandez pas la différence entre un titre et un nom de dépôt, j’en sais rien ! Mais ça n’a pas d’importance. Cliquez sur “Next step”.

RiouxSVN - Créer un nouveau dépôt 2/6
RiouxSVN – Créer un nouveau dépôt 2/6

Sur l’écran suivant, cochez la case “Create trunk, branches and tags directories”. Cliquez sur “Next step”.

RiouxSVN - Créer un nouveau dépôt 3/6
RiouxSVN – Créer un nouveau dépôt 3/6

Sur cet écran, vous pouvez vous abonner aux notifications liées à ce dépôt en cochant la case. Chaque fois qu’un utilisateur effectuera une modification du dépôt, vous recevrez un e-mail. Cela peut-être utile dans certains cas. Vous aurez la possibilité de changer ce comportement plus tard si vous le souhaitez. Cliquez-sur “Confirm creation” pour finaliser la création du dépôt.

RiouxSVN - Créer un nouveau dépôt 4/6
RiouxSVN – Créer un nouveau dépôt 4/6

Le dépôt apparait maintenant dans la liste de vos dépôts. Cliquez sur son titre.

RiouxSVN - Créer un nouveau dépôt 5/6
RiouxSVN – Créer un nouveau dépôt 5/6

Dans cet écran, vous trouverez l’URL de votre nouveau dépôt en haut à gauche. Copiez le (sélectionnez-le puis Ctrl+C). Nous en aurons besoin à la prochaine étape.

RiouxSVN - Créer un nouveau dépôt 6/6
RiouxSVN – Créer un nouveau dépôt 6/6

Synchroniser le client avec le serveur

La dernière étape de la mise en place d’SVN pour ce projet de démonstration, est d’utiliser notre client TortoiseSVN pour lier un dossier de notre ordinateur avec le dépôt qui est hébergé sur RiouxSVN.

Pour cela, créez un nouveau dossier de projet. Voir notre article Organiser vos documents pour des conseils sur le sujet. Puis faites un clic droit sur ce dossier et sélectionnez “SVN Checkout”. Une boite de dialogue s’ouvre, c’est là qu’il faut coller l’URL que nous avons copié à l’étape précédente. Puis cliquez sur OK.

SVN Checkout
SVN Checkout

On vous demandera de renseigner vos identifiants de connexion à RiouxSVN. Cochez la case “Save authentication” si vous ne voulez pas retaper vos identifiants à chaque manipulation. Cliquez sur OK.

Connexion à RiouxSNV

Une boite de dialogue vous affiche la liste des opérations effectuées.

SVN Checkout Finished!
SVN Checkout Finished!

TortoiseSVN a donc copié dans votre dossier de projet les 3 dossiers “trunk”, “tabs, “branches” présents sur le dépôt du serveur. Et vous pouvez effectivement constater leur présence dans l’explorateur de fichiers :

Explorateur du dossier de projet après le premier checkout

Le dossier .svn est un dossier caché. Il peut ne pas apparaitre dans votre explorateur.
Le dossier “trunk” est le dossier principale. Ce sera notre dossier de travail.
Le dossier “tags” est le dossier dans lequel on trouvera les différentes configurations dont on parlait au début de cet article.
Le dossier “branches” trouve son utilité pour des projets complexes. On va le laisser de côte pour l’instant car on n’en a pas besoin. Dîtes-nous en commentaire si vous souhaitez une version Expert de ce tuto.

Si vous ne voyez pas les petits check sur ronds verts, redémarrez votre ordinateur. TortoiseSVN ajoute des petites icônes sur les icônes de l’explorateur pour indiquer l’état de synchronisation des différents fichiers et dossiers du dépôt.

Sauvegarder les premiers fichiers

On oublie souvent de le présenter, mais l’un des des principaux atouts des outils de gestion de version est la sauvegarde. En effet, les fichiers sont tous sur hébergés le serveur afin que tous les clients puissent rester à jour. Et comme chaque évolution est sauvegardée, il est même possible de voyager dans le passé du projet pour retrouver l’état de chaque fichier (voire de ensemble de fichiers) à une date donnée.

Imaginons qu’on vienne de recevoir un cahier des charges pour ce projet de démonstration. Plaçons-le dans un sous-dossier du dossier de projet.

Cahier des charges ajouté au dossier du projet
Cahier des charges ajouté au dossier du projet

Nous voulons ensuite livrer ce nouveau document, ainsi que l’arborescence de sous-dossiers créée, sur le dépôt du serveur, afin que toute l’équipe y ait accès. Pour cela, faites un clic droit sur le dossier trunk, puis sélectionnez “TortoiseSVN”, puis cliquez sur “Add…”.

TortoiseSVN - Ajouter des fichiers 1/4
TortoiseSVN – Ajouter des fichiers 1/4

Une boîte de dialogue s’ouvre pour nous permettre de sélectionner les dossiers et les fichiers à ajouter. Par défaut, tout est coché et nous allons laisser comme ça.

Notez qu’on ne peut pas ajouter un fichier ou un dossier si le dossier dans lequel il se trouve n’est pas lui-même ajouté.

Cliquez sur “OK”.

TortoiseSVN - Ajouter des fichiers 2/4
TortoiseSVN – Ajouter des fichiers 2/4

Encore une fois, TortoiseSVN affiche une boîte de dialogue pour présenter la liste des opérations effectuées. Cliquez sur “OK”.

TortoiseSVN - Ajouter des fichiers 3/4
TortoiseSVN – Ajouter des fichiers 3/4

Un gros “+” bleu est apparu sur les dossiers et le fichier. La coche sur rond vert du dossier “trunk” s’est transformé en un point d’exclamation sur rond rouge.

TortoiseSVN - Ajouter des fichiers 4/4
TortoiseSVN – Ajouter des fichiers 4/4

Le “+” bleu signifie que SVN à pris en compte le fait qu’il va devoir surveiller les évolutions ces fichiers à l’avenir. Cependant, tant que nous n’avons pas synchronisé cette modification (cet ajout) rien n’est encore mis à jour sur le serveur. Et nous pouvons encore annuler cet manipulation par exemple (clic droit -> TortoiseSVN -> Undo Add).

Or le dossier “trunk”, qui lui était surveillé par SVN, présente maintenant un point d’exclamation sur rond rouge pour porter à notre attention que quelque-chose a changé dans ce dossier et n’est pas encore synchronisé avec le dépôt du serveur.

Pour enfin sauvegarder nos modifications sur le dépôt du serveur, faîtes un clic droit sur le dossier du projet, puis “SVN Commit…”

TortoiseSVN - Livrer les modifications 1/4
TortoiseSVN – Livrer les modifications 1/4

Une boite de dialogue s’ouvre pour confirmer la livraison des modifications sur le serveur (beaucoup disent “le commit”). Elle présente un champ pour laisser un message, ainsi que la liste des opérations à livrer. Si nous n’avions pas déjà ajouté notre fichier et nos dossiers, nous aurions pût également le faire directement depuis cette boite de dialogue.

Je vous encourage vivement à laisser un message indiquant pourquoi vous livrez une nouvelle version. Bien que ça ne soit pas obligatoire, c’est une aide inestimable pour vous et les membres de votre équipe. Être capable de se souvenir pourquoi on a fait tel ou telle chose rend de grands services. Profitez-en !

TortoiseSVN - Livrer les modifications 2/4
TortoiseSVN – Livrer les modifications 2/4

Cliquez sur OK.

Une fois de plus, TortoiseSVN affiche une boite de dialogue pour présenter la liste des opérations effectuées. La ligne “Commit to https://svn.riouxsvn.com/naept_demo” indique que les modifications sont envoyées au serveur par exemple.

TortoiseSVN - Livrer les modifications 3/4
TortoiseSVN – Livrer les modifications 3/4

Cliquez sur “OK”

Toutes les sur-icônes de TortoiseSVN repassent au vert. Tout est synchronisé sur le serveur. C’est un peu comme une super sauvegarde. Votre ordinateur pourrait planter, être détruit ou que sais-je, vous pourriez toujours récupérer ce que vous avez sauvegardé sur le serveur !

TortoiseSVN - Livrer les modifications 4/4
TortoiseSVN – Livrer les modifications 4/4

Mettre à jour sa copie

Imaginons maintenant que votre collègue ait commencé à rédiger des spécifications logicielles pour ce projet. Il a ensuite livré ses modifications sur le dépôt du serveur, et comme vous êtes abonné aux notifications liées a ce dépôt, vous avez reçu un e-mail pour vous en informer.

Cependant la mise à jour du répertoire qui se trouve sur votre ordinateur (votre copie du serveur) n’est pas automatique. Il faut la faire manuellement. C’est une bonne habitude de la faire à chaque fois que vous allez commencer à modifier quelque-chose.

Pour mettre votre copie à jour, faîtes un clic droit sur le dossier du projet, puis cliquez sur SVN Update.

TortoiseSVN - Mettre à jour sa copie 1/2
TortoiseSVN – Mettre à jour sa copie 1/2

Comme d’habitude, TortoiseSVN affiche une boite de dialogue pour présenter la liste des opérations effectuées.

TortoiseSVN - Mettre à jour sa copie 2/2
TortoiseSVN – Mettre à jour sa copie 2/2

Si aucune modification n’a été apportée au dépôt depuis votre dernière mise à jour, cette liste sera bien sûr vide.

Gestion de conflits

Que se serait-il passé si nous avions commencé à travailler sur le fichier avant de faire notre mise-à-jour ?

Et bien lors de la mise à jour, TortoiseSVN nous aurait indiqué un conflit ! Rien de bien grave en fait, puisqu’il nous aurait fallu choisir entre l’un des deux fichiers, celui de notre collègue ou le notre. On sait bien lequel on aurait choisi, mais notre pauvre collègue aurait travaillé pour rien…

Une bonne pratique à avoir dans ces cas là, est de toujours verrouiller un fichier avant de commencer à travailler dessus. Ainsi les autres membres du projet ne pourront pas éditer le document tant que vous n’avez pas terminé vos modifications.

Une seconde bonne pratique consiste à toujours commencer par livrer sur le serveur un fichier vide juste après sa création, pour “réserver” sa place en quelques sortes, et vous éviterez tous les conflits de fichiers.

Pour verrouiller un fichier, faites un clic droit dessus puis sélectionnez “TortoiseSVN”, et enfin cliquez sur “Get lock…”

TortoiseSVN - Verrouiller un fichier 1/3
TortoiseSVN – Verrouiller un fichier 1/3

Une boite de dialogue s’ouvre pour vous permettre de confirmer le fichier que vous voulez verrouiller. Vous auriez pu en verrouiller plusieurs en réalisant l’opération sur un dossier plutôt qu’un document. N’oubliez pas de laisser un message à vos collègues pour indiquer qui a verrouillé le document et pourquoi.

TortoiseSVN - Verrouiller un fichier 2/3
TortoiseSVN – Verrouiller un fichier 2/3

L’habituelle petite boite de dialogue vous signifie que le verrouillage s’est bien passé.

TortoiseSVN - Verrouiller un fichier 3/3
TortoiseSVN – Verrouiller un fichier 3/3

Le verrou sera automatiquement levé lors de votre livraison (commit) des modifications, mais vous pouvez également le faire manuellement si vous décidez de ne plus travailler sur le fichier. Pour cela, faîtes un clic droit dessus puis sélectionnez “TortoiseSVN”, et enfin cliquez sur “Release lock…”

TortoiseSVN - Déverrouiller un fichier
TortoiseSVN – Déverrouiller un fichier

Figer une configuration

Maintenant que tout le monde est d’accord pour dire que tous les documents du projet sont finalisés et fonctionnement bien ensemble, il est temps de créer cette fameuse configuration.

Les configurations figées sont placées par convention dans le dossier “tags”. Il s’agit, pour simplifier, d’une copie à l’instant T du contenu du dossier trunk.

Faites un clic droit sur le dossier “trunk” (et pas le dossier du projet), puis sélectionnez “TortoiseSVN”, et enfin cliquez sur “Branch/tag…”

TortoiseSVN - Figer une configuration 1/4
TortoiseSVN – Figer une configuration 1/4

La boîte de dialogue qui s’ouvre permet de créer une branche ou un tag. Voici comment remplir le formulaire pour générer un tag.
Le champs “To path” doit être complété avec “tags/” suivi du nom que vous donnez de la configuration que vous voulez figer. Ce nom est libre mais doit respecter les règles des noms de dossiers (en termes de caractères utilisables). Mettez une règle en place avec votre équipe et respectez là.
Comme pour les livraisons, ajoutez un message qui décrit les changements depuis la version précédente. Ne soyez pas avare sur les explications.
Laissez les autres champs comme tel.

TortoiseSVN - Figer une configuration 2/4
TortoiseSVN – Figer une configuration 2/4

Je ne vous présente plus l’habituel compte rendu des opérations. On remarque bien que c’est une commande de copie (Copy) qui a été effectuée par SVN.

TortoiseSVN - Figer une configuration 3/4
TortoiseSVN – Figer une configuration 3/4

Si maintenant nous nous rendons dans le dossier “tags”, vous trouverez un nouveau dossier qui porte le nom que vous avez renseigné pour cette configuration. Il est possible que vous ayez à faire une mise à jour de votre copie locale du dépôt (voir plus haut) pour mettre à jour le dossier tags.

TortoiseSVN - Figer une configuration 4/4
TortoiseSVN – Figer une configuration 4/4

Si vous devez livrer l’ensemble des fichiers du projet à un client, envoyez-lui ce dossier, ils seront forcément cohérents.

Conclusion

Voilà pour cette introduction à la gestion de configuration documentaire avec SVN. Nous pourrions encore développer d’avantage son utilisation mais cela complexifierait cette première approche. Elle devrait être suffisante pour gérer bon nombre de vos projets. C’est en tout cas cette utilisation que nous en avons depuis plusieurs années sur la majorité de nos projets d’ingénierie industrielle.

Pour plus d’informations sur la gestion de configuration, je vous renvoie vers la documentation de TortoiseSVN, en français, qui est très bien faite : https://tortoisesvn.net/docs/release/TortoiseSVN_fr/tsvn-basics.html

Et vous ?

N’hésitez pas à nous dire en commentaire si vous souhaitez une version expert de cette article avec encore plus de bonnes pratiques sur SVN.

Quel logiciel utilisez-vous pour gérer vos documents ?

Quelles bonnes pratiques avez-vous mises en place avec vos équipes ?

N’hésitez pas à commenter et à partager cet article.

Bonne journée !

📝 Participez à notre Etude sur la documentation de projet.

Related Posts

Leave a Reply