Organiser l’installation de WordPress pour développer un plugin avec Subversion (SVN)

Mis à jour le

  1. 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).

    Répertoire Subversion SVN des plugins WordPress
    Répertoire Subversion SVN des plugins WordPress

    Or, dans une installation locale de WordPress, les plugins en cours de développement sont dans le répertoire /wp-content/plugins et non pas dans le répertoire /trunk.
    Répertoire /wp-content/plugins
    Répertoire /wp-content/plugins

    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.

    Heureusement, Tom McFarlin a publié en 2012 une façon d’organiser l’installation de WordPress sous Subversion qui résout ce problème avec simplicité et élégance.

    Le présent tutoriel est une adaptation (destinée principalement aux débutants francophones) de l’article que Tom McFarlin a publié (en anglais et à destination des développeurs confirmés) ici : Organize Your WordPress Installation For Subversion-Based Development

    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

  2. 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.

      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

    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.

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

    Bien entendu, on suppose ici que avez installé WordPress localement sur votre ordinateur.

    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.

    Création du répertoire /wp-content/plugins/wp-repository
    Création du répertoire /wp-content/plugins/wp-repository

    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 » :

    Cliquer à droite et sélectionner SVN Checkout
    Cliquer à droite et sélectionner 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.

    Copie locale du répertoire SVN de « Recently Updated Posts Widget »
    Copie locale du répertoire SVN de « Recently Updated Posts Widget »

    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 :

    La coche verte signifie que le statut Subversion est normal
    La coche verte signifie que le statut Subversion est normal

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

    Icônes de TortoiseSVN et de TortoiseGIT
    Icônes de TortoiseSVN et de TortoiseGIT

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

    Dépôt local de chaque plugin dans /wp-repository
    /wp-repository

    Vous remarquerez que le répertoire /wp-repository (situé dans /wp-content/plugins) n’est pas visible depuis le tableau de bord de WordPress.

    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.

    wp-repository ainsi que le plugin Recently Updated Posts Widget qu'il contient ne sont pas visibles depuis la page des extensions de WordPress.
    Aucun des plugins de /wp-repository n’est visible depuis la page des extensions de WordPress.
  4. Création des liens symboliques

    Les liens symboliques sont comme des raccourcis. Ce sont des fichiers qui permettent de faire en sorte que tout lien vers un répertoire /A soit redirigé vers un autre /B.

    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 »
        Download Standalone Executable
        Download Standalone Executable

    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 »

    Symbolic Link Creator
    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 :

    Sélectionner /wp-content/plugins
    Sélectionner /wp-content/plugins

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

    Sélectionner /wp-repository/recently-updated-posts-widget/trunk
    Sélectionner /wp-repository/recently-updated-posts-widget/trunk

    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 :

    Même nom que le répertoire du plugin
    Même nom que le répertoire du plugin

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

    Lien symbolique dans /wp-content/plugins
    Lien symbolique dans /wp-content/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.

  5. Développer comme d’habitude

    Ce lien symbolique permet de développer son plugin dans un environnement de développement « intégré » (EDI en français ou IDE en anglais, pour Integrated Development Environment) ou avec un éditeur de code (notepad++ par exemple) et de le tester sur WordPress comme auparavant.

    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).

    Le lien est désormais un plugin WordPress
    Le lien est désormais un plugin WordPress
    Toute modification du plugin sur un des deux répertoires (/trunk ou /wp-content/plugins) est équivalente à une modification 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.

  6. Le bon usage des commandes SVN

    Ayant beaucoup galéré inutilement avec Subversion, je rappelle ici le bon usage des principales commandes SVN (au moins en aide-mémoire personnel) afin d’éviter des manipulations inutiles et chronophages.

    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.

    Si l’explorateur de dépôt permet lui aussi de faire des transferts de fichiers, ils sont vraiment lent. Alors qu’avec les commandes dédiées à cet usage, les transferts sont vraiment rapides.

    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.

    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 :

       Mettre à jour le dépôt SVN WordPress
      Mettre à jour le dépôt SVN WordPress

      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 :

      Conserver dans /tags une version publiée du plugin
      Conserver dans /tags une version publiée du plugin

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

      J'ai remplacé /trunk par l'étiquette /tags/1.4.1
      J’ai remplacé /trunk par l’étiquette /tags/1.4.1

      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 :

        Répertoire /tags
        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).
        Répertoire /trunk
        Répertoire /trunk

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

        Stable tag: 1.4.1 (dernière version publiée)
        Stable tag: 1.4.1 (dernière version publiée)

        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.

        Version trunk non proposée au téléchargement
        Version trunk non proposée au téléchargement
    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.

      Mettre à jour le noyau (core) de WordPress
      Mettre à jour le noyau (core) de WordPress

Si vous avez trouvé une faute d’orthographe, informez-nous en sélectionnant le texte et en appuyant sur Ctrl + Enter

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *