Présentation

Tout développeur de plugin ou de thème sait que le développement de WordPress est géré avec le système [de gestion de versions multiples de fichiers] Subversion (en abrégé SVN).

Avec ce système Subversion, lorsque un plugin WordPress est copié du dépôt SVN WordPress sur l’ordinateur local, quatre répertoires sont importés : /assets, /branches, /tags et /trunk (qui contient la version en cours de développement).

Ainsi, pour développer un plugin WordPress, on est contraint de gérer des fichiers identiques (ou qui devraient l’être) situés dans des répertoires différents :

• dans /trunk, lié via Subversion au dépôt SVN (distant) et qui permet de mettre à jour ce dernier
• dans /wp-content/plugins, ce qui permet de tester le plugin sur WordPress

Cela induit des copies manuelles d’un répertoire vers l’autre et est souvent source d’erreurs ou de vraies prises de tête : on ne sait plus si les fichiers de l’autre répertoire sont vraiment les mêmes que celui sur lequel on travaille et vice versa, bref, on s’y perd très vite.

Les débutants auront une idée du nombre incroyable de manipulations diverses et variées qu’il fallait faire avant que Tom McFarlin ne publie sa solution en regardant cette vidéo en anglais de 10 minutes du tuto suivant : Using Subversion with the WordPress Plugin Directory

Pré-requis à l’usage de la technique de Tom McFarlin

1. Glossaire

   Dans ce tutoriel, on appellera :

   • Dépôt SVN, le dépôt distant situé sur le serveur de WordPress.org qui permet aux utilisateurs de WordPress d’installer ou de télécharger WordPress, ses plugins et ses thèmes.
   • Dépôt local, la copie sur son ordinateur personnel du dépôt SVN de votre plugin (ou thème)
   • indifféremment « dossier » un « répertoire » et vice-versa.

2. Avoir installé un serveur web local sur votre ordinateur

   comme MAMP, WAMP, XAMPP ou autre.

   Les captures d’écran de ce tutoriel sont effectuées à partir d’une installation locale de WordPress avec XAMPP sur Windows 7.

3. Avoir installé et configuré une version de Subversion (SVN)

   Comme TortoiseSVN pour Windows ou celle native de Mac et de Linux en appliquant à la lettre le tutoriel du Core Handbook de WordPress ici : Make WordPress Core: Installing a Version Control System.

   Voir d’autres interfaces graphiques tous systèmes.

   • Sous mac, vous pouvez utiliser SCPlugin
   • rapidSVN s’installe sur toutes les plateformes (Linux, Windows, Mac OS/X, Solaris, etc).

   Les captures d’écran de ce tutoriel sont effectuées avec une installation de TortoiseSVN sur Windows 7.

4. Avoir publié un plugin sur le dépôt de WordPress

   • Un tutoriel très clair expliquant comment publier un plugin prêt à l’emploi sur le dépôt de WordPress avec TortoiseSVN sous Windows est disponible ici : Copier / Coller : Publier son plugin WordPress

   • Un autre sous Mac avec Xcode et svnX se trouve ici  Publier un plugin wordpress sous mac: tuto

5. Installer WordPress lui-même via SVN

   Tom McFarlin ne le précise pas, mais personnellement, je trouve qu’installer WordPress lui-même en appliquant à la lettre le tutoriel du Core Handbook de WordPress permet de tester facilement ses propres plugins avec la dernière version WordPress en cours de développement.

Création d’un répertoire unique qui permet de gérer tous les autres

La première chose à faire est de créer un répertoire /wp-repository dans le répertoire /wp-content/plugins de votre installation locale de WordPress.

Dans ce répertoire /wp-repository, on crée autant de dossiers (vides) que de plugins que l’on développe, puis on y copie (Checkout) chacun de leur dépôt SVN.

Par exemple, j’ai nommé un dossier (vide) /recently-updated-posts-widget du même nom que celui de mon plugin « Recently Updated Posts Widget », puis j’ai cliqué à droite sur « SVN Checkout » :

La fenêtre suivante apparait déjà préremplie, il suffit d’indiquer l’adresse du dépôt SVN ( https://plugins.svn.wordpress.org/… ) dans le champ « URL of repository », puis de cliquer sur OK.

On remarquera que l’icône du répertoire /recently-updated-posts-widget est désormais recouverte par une coche verte qui signifie que son statut SVN est normal :

Pour rappel les différentes icônes de recouvrement de TortoiseSVN et des autres Tortoise[CVS, HG et GIT] sont :

J’ai fait de même pour les autres plugins que je développe et j’ai obtenu :

En effet, il n’a pas la structure d’un plugin WordPress : il ne possède aucun fichier PHP ayant l’entête caractéristique des plugins WordPress.

Création des liens symboliques

Comme expliqué par Tom MacFarlin, il suffit de créer un lien symbolique du répertoire /wp-content/plugins vers la copie locale du répertoire [de développement] /trunk de chaque plugin.

Ces liens symboliques peuvent être créés :

1. Nativement en ligne de commande :

   en se positionnant dans le dossier /wp-content/plugins et taper la commande suivante après avoir remplacé répertoire-du-plugin par celui de votre plugin :

   • sous Mac et Linux :

     ln -s wp-repository/répertoire-du-plugin/trunk répertoire-du-plugin 

   • sous Windows, en mode administrateur :

     mklink /D répertoire-du-plugin wp-repository\répertoire-du-plugin\trunk

2. Avec une interface graphique :

   • Sous Mac, il existe SymbolicLinker qui est disponible au téléchargement ici SymbolicLinker.
   • Sous Windows, il existe « Symlinker » qui est développée en Open Source sur GitHub et téléchargeable ici  Symlinker.
     Le lien de téléchargement se situe dans la section « Downloads »
     

     

Les captures d’écrans qui suivent sont celles de Symlinker sous windows 7.

L’interface graphique Symlinker sous Windows 7 se présente sous la forme d’une fenêtre nommée « Symbolic Link Creator »

Par exemple, pour le plugin que j’ai écrit « Recently Updated Posts Widget », j’ai créé un lien symbolique du répertoire /wp-content/plugins vers le répertoire /wp-repository/recently-updated-posts-widget/trunk nommé exactement recently-updated-posts-widget (comme le nom du dossier dans lequel se trouve le plugin).

Remplir le champ « Link Folder » en cliquant sur le bouton « Explore » qui ouvre un explorateur :

Ensuite remplir le champ « Destination Folder » en cliquant sur le bouton « Explore » suivant :

Et enfin entrer le nom du lien, c’est à dire le nom du dossier du plugin, dans cet exemple « recently-updated-posts-widget », puis cliquez sur « Create Link » et confirmez à la demande de la nouvelle fenêtre :

Le lien apparait désormais dans le répertoire des plugins :

Par la suite WordPress et l’éditeur de code source (notepad++, par exemple) agiront tous deux comme si ce lien symbolique était un plugin comme un autre.

Développer comme d’habitude

Le plugin est développé normalement, c’est à dire comme s’il se trouvait réellement dans le répertoire /wp-content/plugins. D’ailleurs à l’écran, on croit vraiment qu’il y est (alors que ce n’est que l’image virtuelle du répertoire /trunk).

Ainsi, on peut continuer à développer son plugin directement dans le dossier /wp-content/plugins avec notepad++ comme on a l’habitude de le faire. Le plus pratique étant quand même de développer le plugin directement dans /wp-repository.

Il est toujours aussi facile de passer de l’édition du code source du plugin au test de son fonctionnement sur WordPress puis de retourner travailler sur son code source comme on le fait fréquemment.

Le développement du plugin terminé, il suffit de mettre à jour le dépôt SVN (commit), puis d’étiqueter la nouvelle version comme on le fait habituellement. Ce qui est très simple à faire puisque le répertoire local du plugin est lié via Subversion à celui du dépôt SVN.

Le bon usage des commandes SVN

Après avoir apporté (pour mon usage personnel) une amélioration au plugin StatPress Reloaded, je me suis dit qu’ayant moi-même bénéficié du partage de ce plugin, je ne devais pas garder pour moi le fruit de ce travail et en faire profiter les autres. J’ai alors cherché à le publier sur le dépôt de WordPress après avoir baptisé ce plugin (un peu au hasard) « StatPress Visitors ». Malheureusement je n’ai pas trouvé d’explications simples en français sur l’usage de Subversion sur le dépôt de WordPress (j’ai certainement mal cherché).

Les tutoriels en anglais donnaient une liste de lignes de commandes Linux à exécuter (alors que j’utilisais Windows XP). Et au lieu d’expliquer le principe de l’usage de Subversion sur le dépôt WordPress, les tutoriels expliquaient pas à pas la technique sous Linux, ce qui les rend laborieux sous Windows. N’ayant pas envie de me prendre la tête, je suis allé au plus vite en utilisant l’explorateur de dépôt (SVN repo-browser) pour publier finalement ce plugin en février 2011.

Cerise sur le gâteau, cette façon de faire multiplie les glisser-déposer à n’en plus finir : une vraie galère !

Cet été, ayant mis à jour quelques-uns de mes plugins, le problème s’est à nouveau posé. Définitivement convaincu que je devais enfin apprendre à utiliser Subversion, j’ai cherché à nouveau des explications sur l’usage de Subversion avec WordPress.

Faire le support en anglais de mes plugins sur le dépôt de WordPress pendant plusieurs années m’a évidemment fait progresser en anglais technique. Immédiatement séduit par la technique de Tom McFarlin, je lui ai demandé l’autorisation de traduire son article. Cela m’a amené à faire enfin l’effort de bien comprendre Subversion.

Pour ce faire, j’ai lu les forums de développeurs anglais, les documentations WordPress et Subversion officielles ainsi que divers articles de vulgarisation. Pour finir, des tests sur le dépôt de certains de mes plugins m’ont assuré que j’avais bien compris. Ayant beaucoup appris, je peux ainsi aujourd’hui partager ce savoir-faire.

1. Principales commandes de SVN

   Une brève description donnant le lien vers chaque page de la documentation officielle de TortoiseSVN (en anglais et en français) est visible ici : Voir les opérations usuellement effectuées avec Subversion.

   Les opérations habituellement effectuées avec Subversion sont :

   • Checkout ou Extraire, qui copie localement tous les répertoires et fichiers existant sur le dépôt SVN
   • Update ou Mettre à jour, qui met à jour le dépôt local avec les derniers fichiers modifiés sur le dépôt SVN
   • Commit ou Livrer, qui a l’inverse de l’update, met à jour le dépôt SVN avec les fichiers modifiés localement
   • Branch/tag ou Branche/Étiquette, qui permet de conserver dans /tags une version publiée du plugin
   • Repo-browser ou SVN Navigateur de dépôt, qui permet d’explorer le dépôt SVN
   • Create Patch ou Créer un patch, utilisé par les développeurs du noyau de WordPress. Il permet de proposer à l’équipe de développement de WordPress une modification du noyau de WordPress
   • Apply Patch ou Appliquer un patch, utilisé par les développeurs du noyau de WordPress. il permet d’appliquer un patch sur son dépôt local
   • Revert ou Revenir en arrière, qui permet de supprimer un patch ou d’annuler une modification.

2. Mise à jour du dépôt SVN (Commit)

   Pour envoyer sur le dépôt SVN de WordPress.org les modifications effectuées localement, il suffit de cliquer à droite sur le dossier du plugin ayant l’icône « modified », puis sélectionner SVN Commit :
   

   

   
   Vous remarquerez que l’icône du plugin est passée à « normal » : les deux dépôts étant identiques.

   Voir : In what directory should I put my files?

3. Étiqueter la version publiée dans le dépôt SVN (Tag)

   Étiqueter, c’est créer un lien (appelé aussi « copie bon marché ») du répertoire /tags vers la branche correspondante de l’arbre de développement qui évite au système SVN de faire une copie complète supplémentaire de cette même branche.

   Le bon usage des étiquettes permet de développer un plugin dans le répertoire /trunk du dépôt SVN sans que cette version ne soit diffusée prématurément auprès des utilisateurs du plugin comme expliqué au paragraphe d) ci-dessous.

   Pour étiqueter, cliquer à droite sur le dossier /trunk, puis sélectionner SVN Branch/Tag :

   

   Il apparaît la fenêtre suivante indiquant le répertoire qui sera conservé dans le répertoire /tags.

   

   
   Il faut modifier le champ To path: déjà pré-rempli en remplaçant /trunk par /tags/1.4.1 dans l’exemple de mon plugin (la dernière version publiée).

   Voir : How should I name my tags (a.k.a. releases)?

4. Comment développer le plugin dans le répertoire /trunk du dépôt SVN ?

   Il est possible de développer le plugin dans le répertoire /trunk du dépôt SVN de WordPress sans que ces versions en développement ne soient disponibles au téléchargement pour les usagers de WordPress.

   Pour ce faire, il y a deux étapes à respecter. Ce sont :

   1. Étiqueter la dernière version publiée dans le répertoire /tags :

      

   2. Champ Stable tag: de readme.txt

      Si le champ Stable tag: de readme.txt est 1.4.1 et que /tags/1.4.1/ existe, le système proposera automatiquement son contenu (celui de /tags/1.4.1) au téléchargement (sans regarder dans /trunk).

      

      Voir : Can I specify what version of my plugin the WordPress.org Plugin Directory should use?
      

      

      L’entête du fichier PHP, recently-updated-posts.php peut de ce fait avoir n’importe quel numéro de Version: comme par exemple trunk.
      

      

5. Publication dans le dépôt SVN (Release)

   Pour publier un plugin, d’après les explications du paragraphe précédent, il suffit de mettre à jour le répertoire /trunk du dépôt SVN (Commit) en ayant les champs identiques suivants :

   • Stable tag: de readme.txt
   • Version: du fichier PHP principal

   Par exemple, pour publier la dernière version de mon plugin, j’ai écrit  :

   • Stable tag: 1.4.1 dans /trunk/readme.txt
   • Version: 1.4.1 dans /trunk/recently-updated-posts.php

   WordPress recommande de versionner les plugins avec la numérotation usuelle, voir : How should I name my tags (a.k.a. releases)?.

   C’est à dire de présenter les versions avec trois numéros séparés par des points comme par exemple 4.0.1, les deux premiers numéros correspondent à la version. Remarquez que WordPress est passé de 3.9 à 4.0 (et non pas à 3.10). Le troisième numéro est celui des versions de sécurité qui corrige les failles et bugs trouvés.

   Une fois publié, le conserver dans le répertoire /tags comme expliqué au paragraphe c) ci-dessus.

6. Mettre à jour le noyau de WordPress via SVN (Update)

   Si vous avez installé WordPress via Subversion localement comme recommandé sur le Core Handbook de WordPress, vous devez mettre à jour quotidiennement le noyau (core) de WordPress de façon à tester les plugins avec la dernière version de WordPress (alpha, beta ou Release candidate) en cours de développement.

   Pour ce faire, il suffit de cliquer à droite sur le dossier /wordpress-svn et de sélectionner SVN Update.