Cet article liste l’ensemble des commandes subversion utiles lors de la publication d’un plugin sur le SVN de WordPress.
Il ne s’agit pas ici d’expliquer en détails le fonctionnement de SVN, mais uniquement de rappeler les principes et les commandes de base qui peuvent facilement être oubliées quand on ne met pas à jour ses plugins très souvent.
Dépôt d’un nouveau plugin
Récupération du contenu du dépôt SVN (checkout)
La première étape est de créer le dossier local qui va accueillir une copie du dépôt SVN.
$ mkdir mon-dossier-local
Il faut ensuite effectuer le checkout du projet. Le checkout est l’opération consistant à récupérer les fichiers existant dans le dépôt SVN. Cette opération ne se fait pas nécessairement à chaque fois…
$ svn co https://plugins.svn.wordpress.org/nom-du-plugin mon-dossier-local > A mon-dossier-local/assets > A mon-dossier-local/branches > A mon-dossier-local/tags > A mon-dossier-local/trunk > Checked out revision 1654809.
Le A indique que subversion a ajouté (« A » pour « Add ») tous les répertoires du dépôt SVN dans le dossier local mon-dossier-local que vous avez créé.
Ajout des fichiers du plugin dans le dépôt SVN (commit)
Vous devez maintenant copier tous les fichiers de votre plugin dans le dossier mon-dossier-local/trunk. Cette opération peut être réalisée via le gestionnaire de fichiers de votre système d’exploitation ou via la commande adaptée.
$ cp -avR source/ destination/
Attention à copier les fichiers du plugin directement dans trunk sans le dossier parent.
La copie du plugin se trouve dans le dossier trunk. Il faut maintenant vous positionner dans le dossier local puis déclarer les dossiers à ajouter dans le dépôt. Dans l’exemple de code, je déclare l’intégralité des dossiers trunk et assets.
$ cd mon-dossier-local mon-dossier-local/$ svn add trunk/* assets/* > A assets/banner-772x250.png > A assets/icon-128x128.png > A trunk/nom-du-plugin.php > A trunk/readme.txt
Tout est prêt pour le commit ou checkin. Cette opération consiste à mettre à jour le dépôt SVN à partir de la copie disponible dans votre dossier local. Vous devez saisir un message indiquant la raison de la mise à jour. Une nouvelle révision sera alors créée sur le dépôt.
mon-dossier-local/$ svn ci -m 'Adding first version of my plugin' > Adding assets/banner-772x250.png > Adding assets/icon-128x128.png > Adding trunk/nom-du-plugin.php > Adding trunk/readme.txt > Transmitting file data . > Committed revision 1654810.
En cas de problème d’accès « Access forbidden« , il est possible de vous identifier lors du commit.
mon-dossier-local/$ svn ci -m 'Adding first version of my plugin' --username nomutilisateur --password motdepasse
Mettre à jour les fichiers d’un plugin
Pour que cela fonctionne, il faut que l’opération de checkout ait déjà été effectuée pour avoir un copie du dépôt en local.
On va commencer par vérifier que la copie locale est bien à jour par rapport au dépôt. Si la copie locale n’est pas à jour, les fichiers concernés seront alors téléchargés.
$ cd mon-dossier-local mon-dossier-local/$ svn up > At revision 1654810.
Vous pouvez maintenant effectuer toutes les modifications que vous souhaitez dans les fichiers de votre plugin. Une fois les modifications effectuées, il s’agit de vérifier les différences entre votre copie locale et celle du dépôt.
mon-dossier-local/$ svn stat > M trunk/nom-du-plugin.php
Le M (« M » pour « Modified ») indique que le fichier trunk/nom-du-plugin.php est différent entre le dossier local et la version sur le dépôt.
Pour avoir le détails des modification effectuées, vous pouver utiliser la commande diff.
mon-dossier-local/$ svn diff
Une fois que toutes les vérifications ont été effectuées, il suffit d’effectuer un commit.
mon-dossier-local/$ svn ci -m 'Update of my amazing plugin' > Sending trunk/nom-du-plugin.php > Transmitting file data . > Committed revision 1654811.
Si vous rencontrez des problèmes de droits « Access forbidden« , il est possible de vous identifier lors du commit.
mon-dossier-local/$ svn ci -m 'Update of my amazing plugin' --username nomutilisateur --password motdepasse
Si vous avez ajouté des nouveaux fichiers à votre plugin, il faut penser à les ajouter au dépôt.
mon-dossier-local/$ svn add trunk/nouveau-fichier.php
« Tagger » une nouvelle version
Les notions de tronc, de branches et de tags sont spécifiques aux logiciels de contrôle de versions. C’est ce qui explique pourquoi les dossiers trunk branches et tags ont été créés lors du checkout initial.
- Tronc : correspond à la version principale du programme, le développement « officiel ».
- Branche : il s’agit d’un développement « secondaire ». Créé soit pour ajouter de nouvelles fonctionnalités, soit parce que le développement va prendre une autre direction. Une branche peut ensuite être fusionnée dans le « tronc », disparaître ou donner lieu à un nouveau programme.
- Tags : correspond à une releaser du programme, c’est à dire un version du programme. La création de tag permet de passer facilement d’une version du programme à une autre.
À chaque fois que vous allez créer une nouvelle version de votre plugin, vous allez devoir tagger la version en question. Cela permet aux utilisateurs de choisir facilement la version la plus récente (ou une précédente). Cela permet de suivre les modifications plus facilement et permet à WordPress.org de connaître la version du plugin à télécharger en fonction de la version de WordPress des utilisateurs.
Pensez à mettre à jour le champ Stable tag dans le readme.txt du plugin.
On effectue ensuite la copie du plugin dans le dossier tags.
mon-dossier-local/$ svn cp trunk tags/2.0 > A tags/2.0
Comme pour chaque modification, il faut terminer par un commit.
mon-dossier-local/$ svn ci -m "tagging version 2.0" > Adding tags/2.0 > Adding tags/2.0/nom-du-plugin.php > Adding tags/2.0/readme.txt > Committed revision 1654812.
Ressources WordPress.org
- Utiliser Subversion avec le répertoire de plugins WordPress :
https://developer.wordpress.org/plugins/wordpress-org/how-to-use-subversion/ - FAQ sur le répertoire de plugins WordPress :
https://developer.wordpress.org/plugins/wordpress-org/plugin-developer-faq/ - Exemple de fichier readme.txt standard :
https://wordpress.org/plugins/developers/#readme - Validateur de fichier readme.txt :
https://wordpress.org/plugins/developers/readme-validator/ - Gestion des éléments complémentaires (assets) du plugin (bannière, logo) :
https://developer.wordpress.org/plugins/wordpress-org/plugin-assets/ - Règles de fonctionnement du répertoire des plugins WordPress :
https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/
Sauf mention contraire*, l'article Publier un plugin sur le SVN de WordPress et son contenu par Julien Crego sont mis à disposition selon les termes de la licence Creative Commons
Attribution - Pas d’Utilisation Commerciale - Partage dans les Mêmes Conditions 4.0 International
Cette licence vous permet de remixer, arranger, et adapter cette œuvre à des fins non commerciales tant que vous créditez la source en citant le nom des auteurs et que les nouvelles œuvres sont diffusées selon les mêmes conditions.
* Cette notice est intégrée automatiquement à la fin de chaque article de ce site.