Astuces

Publier et synchroniser une extension WordPress en utilisant GIT

Publier une extension wp.org est facile et rapide ! Par contre, le faire de manière à prendre en compte tous les points d’attentions et surtout réaliser une extension complète (détails ci-dessous), c’est une autre paire de manches.
Pour avoir publié 2-3 extensions récemment sur wp.org, je vous assure que ce n’est pas une mince affaire !

Voyons ensemble quelles sont les étapes indispensables pour publier une extension (complète) sur wp.org et assurer des déploiements automatisés en utilisant GIT.

Les prérequis

1. GIT

Ce qu’il faut noter ici c’est l’utilisation d’un outil de versionning GIT et j’utilise comme service, pour héberger, Github.

2. Un terminal de ligne de commandes

Nous aurons besoin d’exécuter un script depuis une invit de ligne de commandes. Sur Mac le terminal est natif, mais sur Windows ¯_(ツ)_/¯. Plus sérieusement, avec GIT GUI, vous avez logiquement une invit de commandes (GIT BASH).

3. Une extension prête pour le grand saut

Il vous faudra une extension fonctionnelle, que vous aurez préalablement testé en locale afin de maximiser vos chances d’être accepté.

4. Un compte WordPress.org

La toute première étape, est d’utiliser votre compte de la plateforme WordPress.org. Vous en aurez besoin pour publier une extension, poster des articles sur le forum, éditer le codex. Si vous en avez déjà un, tant mieux, sinon créez en un.

Une extension aux petits oignons

En 4 petites étapes vous allez avoir une extension détaillée et brandée pour wp.org, prenons BEA – Media Analytics.

1. Readme

Le readme de votre extension est le fichier qui servira à wp.org d’afficher toutes les informations (auteur, participants, description, FAQ, screenshots, détails d’installation, etc).

La documentation officielle est très complète mais complexe à ce sujet. Pour faire simple il suffit d’utiliser un outil en ligne et très intuitif, un readme generator : https://tools.wedevs.com/readme
Au cas où, validez votre fichier avec ce readme validator : https://wordpress.org/plugins/developers/readme-validator/

2. Bannière

En se basant sur les détails de la documentation, il faudra créer à minima une image qui sera affichée comme bannière (Normal Banner). Pour bien faire, vous pouvez contribuer jusqu’à 4 formats, moi je ne fais que le Normal Banner + High-DPI (Retina) :

  • Normal Banner : banner-772x250.(jpg|png)
  • Normal Banner (RTL) : banner-772x250-rtl.(jpg|png)
  • High-DPI (Retina) : banner-1544x500.(jpg|png)
  • High-DPI (Retina RTL) : banner-1544x500-rtl.(jpg|png)

3. Logo

C’est la petite image qui s’affichera dans le BO des extensions d’un site lors de la recherche / installation mais également sur wp.org à côté de la bannière. La documentation précise qu’il en faut à minima un (Normal), le mieux et d’avoir les 2 formats (Normal + High-DPI (Retina)). Ou alors juste le SVG qui va s’adapter le mieux au resize :

  • Normal : icon-128x128.(png|jpg)
  • High-DPI (Retina) : icon-256x256.(png|jpg)
  • SVG : icon.svg

4. Screenshots

Ce sont les images qui sont affichées dans la galerie sur la page wp.org de l’extension. Leurs noms doivent respecter une nomenclature, surtout qu’ils seront utilisés dans le readme.txt. Disons qu’il faut bien comprendre qu’il y a la partie « stockage », dans l’extension, puis la partie « affichage » qui se réalise au niveau du readme.txt.

Proposer votre extension sur WP.org

Maintenant que votre extension est fin prête pour être publiée, il faut la proposer à l’équipe « Plugin Directory Team ». Il vous faudra un nom, un « permalien » et l’extension sous le format .zip.
Une fois envoyé, le mécanisme manuel de validation peut prendre entre quelques heures à plusieurs jours. Il faudra être patient !

Automatiser les déploiements

Ce qu’il faut savoir c’est que wp.org utilise SVN alors que la plupart des développeurs utilisent GIT. C’est donc le passage de l’un vers l’autre que l’on va automatiser, même si à la mano c’est faisable.

On utilisera le script WP Plugin GIT SVN Sync : https://github.com/rayrutjes/wp-plugin-git-svn-sync

Cette mise en place se traduit en 4 étapes :

1. Adapter votre extension

Pour un usage optimal du script, il faut mettre en place au sein de votre extension quelques modifications :

  • Spécifier quel dossier sera utilisé pour les assets : screenshots, cover, logo.
    Par défaut ces derniers devraient être dans .wordpress.org, mais vous pouvez les mettre autre part.
  • Ajouter un fichier permettant d’ignorer, lors de la synchronisation, certains autres fichiers inutiles. Idéalement il faut que votre extension soit minimaliste sur WP.org. Voici un exemple avec certains fichiers inutiles du .distignore.

2. Créer un dossier pour les manipulations

Dans mon dossier avec tous mes projets, j’ai créé un dossier git-to-wp dans lequel j’ai mes extensions qui ont pour but d’aller sur WordPress.org, puis un dossier pour votre extension.

3. Cloner le script en local

Dans ce dossier git-to-wp, clonez le repository de WP Plugin GIT SVN Sync. Personnellement, j’avais fait l’erreur de le mettre dans chaque dossier d’extension, c’est inutile et compliqué à l’usage.
Vous pourriez aussi juste télécharger le .sh alors que le cloner vous permet également de le maintenir à jour.

4. Lancer le script

Depuis le dossier de  votre extension, précisez bien les arguments attendus pour réaliser le sync et lancez la commande :

  • --plugin-name : c’est le slug de l’extension sur WP.org.
  • --svn-user : votre identifiant WP.org avec lequel vous avez proposé votre extension.
  • --git-repo : le repository GIT où est stockée votre extension.
  • --assets-dir : le dossier ou sont stockés les assets (screenshots, logo, cover). Par defaut dans .wordpress.org.

Voici un exemple complet de la commande pour l’extension BEA Media Analytics :

../wp-plugin-git-svn-sync/sync.sh --plugin-name="bea-media-analytics" --svn-user=MaximeCulea --git-repo="https://github.com/BeAPI/bea-media-analytics"

Petite astuce: pour éviter de devoir retaper la commande entière la prochaine fois, créez un .sh ( git-towp-org.sh) dans votre dossier d’extension et sauvegarder cette commande.

Que ce passe t-il concrètement derrière ce script ?

Ce script va créer dans votre dossier d’extension un dossier GIT, un clone de votre repository qui sera la source pour le script afin de réaliser la synchronisation vers SVN. Il y a aura donc aussi un autre dossier SVN, dans lequel le script a réalisé les traitements nécessaires afin d’envoyer le tout sur le SVN de wp.org.

L’arborescence des dossiers

Ce qui ressemblera à la fin à quelque chose de la sorte :

Lancer le script de manière automatique

Actuellement vous devez lancer le script à la mano. Hors moi, dans le but d’accélérer et d’optimiser encore plus le process, je voudrais que toutes les modifications poussées sur la branche master (tag ou pas tag) soit automatiquement sur WordPress.org.

Je pense que cela va s’orienter autour des webhooks de Github et/ou dans l’utilisation de Buddy Works pour lancer des tâches automatiquement.

Bref, je ferais des tests et quand j’aurais trouvé la meilleure manière de le faire, je rédigerais un article pour vous montrer comment le mettre en place.

Votre extension est sur WP.org !

Voilà ! Vous pouvez donc ajouter des features à votre extension, puis en 2-3 secondes les déployer sur WP.org et ainsi les proposer à la communauté plus rapidement et facilement.
Facile, rapide, fini le stress des déploiements 😉


Pour finir, laissez-moi dans les commentaires les solutions alternatives que vous utilisez ? Si elles sont plus ou moins complètes ?
Et sinon si vous avez réussi à gagner du temps en utilisant cette méthode ?

WordPressement vôtre !