SVN

Ce guide a pour objectif de vous présenter le fonctionnement, la configuration et l'utilisation du service Subversion (SVN) intégré à Tuleap. Nous nous concentrerons sur les fonctionnalités offertes par Tuleap pour gérer vos dépôts de code source.

Prérequis : se familiariser avec Subversion

Apprendre les concepts de Subversion

Avant de manipuler les outils, comprendre le fonctionnement de SVN est essentiel.

Le livre "Version Control with Subversion" (Le "SVN Book"), accessible en ligne gratuitement, est la ressource la plus complète pour apprendre le fonctionnement de SVN, de la base aux concepts les plus avancés comme les branches et les fusions.

Choisir un client SVN

Un client SVN est le logiciel que vous installerez sur votre ordinateur pour communiquer avec le dépôt hébergé sur Tuleap.

• TortoiseSVN : Le client le plus populaire pour Windows. Il s'intègre directement à l'explorateur de fichiers, permettant de réaliser toutes les opérations SVN (commit, update, etc.) via un simple clic-droit sur vos fichiers.

• Ligne de commande (client svn) : La méthode la plus directe et universelle. Le client s'installe via le gestionnaire de paquets de votre distribution.

• Également, la plupart des environnements de développement (IDE) modernes intègrent un support pour Subversion, soit nativement, soit via des extensions. Pensez à vérifier les options d'installation sur votre IDE favori.

Pré-requis

• Le service "SVN" doit être activé dans l'administration de votre instance Tuleap et dans l'administration de votre projet.

• Vous devez disposer d'un client Subversion (svn) sur votre poste de travail.

Accéder au service SVN

La page d'accueil du service SVN liste tous les dépôts existants du projet. Chaque carte de dépôt affiche les informations du dernier commit et donne un accès rapide à l'administration (si vous en avez les droits). Vous pouvez également créer de nouveaux dépôts SVN depuis cette page.

Créer un dépôt SVN

1. Depuis la page d'accueil du service SVN, cliquez sur "Créer un nouveau dépôt SVN".

2. Saisissez un nom unique pour le dépôt.

3. Validez la création.

Le dépôt est créé avec une structure de répertoires initiale (trunk, branches, tags) et les permissions par défaut du projet.

Info

Vous devez être administrateur SVN du projet pour créer un dépôt. Par défaut, les administrateurs du projet disposent de ce rôle.

Naviguer dans un dépôt

L'interface web permet d'explorer le contenu d'un dépôt SVN sans avoir besoin d'un client Subversion installé. Vous pouvez :

• Naviguer dans l'arborescence des répertoires et fichiers.

• Consulter le contenu d'un fichier.

• Voir l'historique des révisions d'un fichier.

• Comparer deux révisions du même fichier (diff).

• Consulter l'annotation ligne par ligne d'un fichier (blame) pour savoir qui a modifié chaque ligne et quand.

• Connaître le chemin racine du dépôt et la commande de checkout.

Info

L'accès au navigateur web nécessite une authentification. Seuls les utilisateurs disposant des droits de lecture sur le dépôt peuvent le consulter.

Authentification

Deux méthodes d’authentification sont disponibles pour les opérations nécessitant une authentification (par exemple : commit, checkout sur un projet privé) :

• Mot de passe : Vous pouvez utiliser vos identifiants Tuleap (dans le cas où vous ne vous authentifiez pas via OIDC)

• Personal Access Key : Vous pouvez utiliser un Personal Access Key avec le scope SVN à la place de votre mot de passe. C'est la méthode recommandée pour les scripts et les outils automatisés.

Paramètres et administration

Les fonctions d'administration sont accessibles via le bouton "Paramètres" sur la page d'accueil du service SVN ou lors de la navigation dans un dépôt.

Info

Vous devez être administrateur SVN du projet pour accéder aux paramètres. Les administrateurs du projet disposent automatiquement de ce rôle. D'autres groupes d'utilisateurs peuvent être autorisés via la configuration des permissions du projet.

Notifications email

Tuleap peut envoyer un email à chaque commit dans le dépôt. Vous pouvez configurer plusieurs notifications, chacune avec :

• Chemin surveillé (Chemins surveillés) : le chemin SVN sur lequel les notifications sont envoyées (par exemple /trunk, /branches/v2).

• Destinataires : utilisateurs, groupes d'utilisateurs ou adresses email.

Un en-tête de sujet (Entête du sujet) personnalisable peut être défini par dépôt pour faciliter le tri dans votre boîte de réception.

L'email contient le message de commit, l'auteur, la liste des fichiers impactés et des liens vers le diff dans l'interface web Tuleap.

Contrôle d'accès

Permissions par défaut

Les permissions d'accès SVN par défaut dépendent du statut du projet (public ou privé) et du type d'utilisateur :

Info

Si le mode "utilisateurs restreints" est activé sur la plateforme, seuls les membres du projet ont accès par défaut. Tous les accès au code source sont enregistrés et consultables dans les Access Logs.

Permissions personnalisées

En tant qu'administrateur SVN, vous pouvez redéfinir les permissions d'accès en éditant le fichier de contrôle d'accès du dépôt. La syntaxe suit le format standard SVN :

[chemin]
nom = permission

Où :

• chemin est le chemin relatif dans le dépôt.

• nom est un login Tuleap, un nom de groupe précédé de @, ou * pour tout utilisateur enregistré.

• permission est r (lecture seule), rw (lecture + écriture), ou vide (accès interdit).

Exemples :

Restreindre l'accès en écriture à une équipe spécifique :

[/]
* =
@members = r
@staff = rw

Restreindre l'accès à un sous-dossier :

[/secret]
@members =
@staff = rw

Attention

Les permissions sont cumulatives et la dernière définition l'emporte. Il est recommandé d'utiliser uniquement des groupes d'utilisateurs Tuleap pour définir les permissions.

Historique des versions du fichier d'accès

Chaque modification du fichier de contrôle d'accès est versionnée. Vous pouvez consulter l'historique des versions et revenir à une version antérieure via le sélecteur de versions dans l'interface d'édition. Cette fonctionnalité permet de corriger rapidement une erreur de configuration sans risque.

Info

Les permissions par défaut sont générées automatiquement et ne peuvent pas être modifiées. Vous éditez des permissions supplémentaires qui s'ajoutent en dessous. Pour plus de détails sur la syntaxe, consultez le Subversion Book - Path-Based Authorization.

Tags non modifiables (Immutable Tags)

Les tags non modifiables permettent de protéger certains chemins du dépôt contre les modifications. Une fois un fichier créé dans un chemin non modifiable, il ne peut être ni modifié ni supprimé, mais de nouveaux fichiers peuvent être ajoutés.

Exemple : avec un tag non modifiable sur /tags :

Liste globale d'exceptions

Vous pouvez définir des chemins dans la liste globale d'exceptions pour autoriser l'ajout de contenu dans des sous-dossiers d'un chemin non modifiable.

Exemple : avec un tag non modifiable sur /tags et une exception sur /tags/module* :

Règles de commit

Chaque dépôt SVN peut être configuré avec des règles appliquées au moment du commit :

• Référence obligatoire : si activée, chaque commit doit contenir une référence vers un Artifact Tuleap (par exemple art #123). Les commits sans référence sont rejetés.

• Message de commit modifiable : si activée, le message de commit peut être modifié après coup via svn propset --revprop. Par défaut, cette option est désactivée pour garantir l'intégrité de l'historique.

Info

Ces règles sont configurables par dépôt, dans l'onglet "Paramètres" du dépôt SVN, ou via l'API REST.

Taille maximale de fichier

L'administrateur de la plateforme peut définir une taille maximum de fichier individuel (en mégaoctets) applicable à l'ensemble des dépôts SVN. Si un commit contient un fichier dépassant cette limite, il est automatiquement rejeté. Les fichiers existants qui dépassent la limite ne peuvent plus être modifiés, uniquement supprimés.

Supprimer et restaurer un dépôt

En tant qu'administrateur SVN, vous pouvez supprimer un dépôt depuis ses paramètres. Le dépôt passe en état "en attente de suppression", ce qui laisse la possibilité de le restaurer depuis la section d'administration avant sa suppression définitive.

Références croisées avec les artifacts

L'intégration de SVN dans Tuleap offre un mécanisme de références croisées bidirectionnelles entre les commits SVN et les Artifacts :

• Dans un message de commit SVN, utilisez art #123, bug #456, task #789, etc. pour créer un lien vers un Artifact. La référence est automatiquement transformée en lien cliquable.

• Dans un Artifact, utilisez revision #YYY ou rev #YYY pour créer un lien vers un commit SVN.

Astuce

Il est considéré comme une bonne pratique de toujours référencer un Artifact dans les messages de commit, et inversement, de mentionner les numéros de révision dans les commentaires de suivi des Artifacts.