Publier son bloc sur le répertoire WordPress.org : le guide complet

Publier un bloc sur le répertoire officiel de WordPress.org donne accès à une distribution potentiellement énorme : des millions d’installations WordPress peuvent découvrir et installer le plugin directement depuis leur tableau de bord, sans jamais visiter un site tiers. Mais cette visibilité a une contrepartie : une revue humaine, parfois exigeante, avant toute première acceptation.

Ce guide détaille les étapes concrètes pour préparer un plugin de bloc à la soumission, le contenu attendu dans le readme.txt, les points de sécurité les plus scrutés lors de la revue, et le fonctionnement du dépôt SVN une fois le plugin approuvé.

Structure minimale attendue

Un plugin de bloc destiné au répertoire suit une structure assez standard, proche de celle générée par @wordpress/create-block. L’en-tête du fichier principal du plugin doit contenir les métadonnées classiques, avec une attention particulière portée à trois champs souvent source de rejet : License, Requires at least et Requires PHP, qui doivent être cohérents avec le code réellement livré.

/**
 * Plugin Name:       Bandeau d'alerte WP Moderne
 * Description:       Un bloc pour afficher des messages d'alerte contextuels.
 * Version:           1.0.0
 * Requires at least: 6.4
 * Requires PHP:      7.4
 * Author:            Clément Hadrot
 * License:           GPL-2.0-or-later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       wpmoderne-bandeau-alerte
 */

La licence est un point non négociable : le répertoire n’accepte que des plugins sous licence compatible GPL. Un plugin qui embarque une bibliothèque JavaScript sous une licence incompatible, même de façon marginale, sera rejeté lors de la revue.

Le readme.txt, vitrine et formalité technique

Le fichier readme.txt, au format spécifique de WordPress.org (proche du Markdown, mais avec ses propres conventions), sert à la fois de page de présentation publique et de source des métadonnées affichées dans le catalogue. Les en-têtes obligatoires en haut de fichier sont scrutés automatiquement :

=== Bandeau d'alerte WP Moderne ===
Contributors: clementhadrot
Tags: bloc, alerte, notification, gutenberg
Requires at least: 6.4
Tested up to: 6.7
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Un bloc simple pour afficher des messages d'alerte contextuels dans vos articles et vos pages.

Le champ Stable tag mérite une vigilance particulière : il doit correspondre exactement à un tag existant dans le dépôt SVN, faute de quoi WordPress.org propose la mauvaise version aux utilisateurs, voire aucune version du tout.

Ce que la revue de sécurité contrôle en priorité

La première soumission d’un plugin passe par une revue manuelle, réalisée par l’équipe du répertoire. Sur les blocs, les points suivants reviennent systématiquement dans les retours de revue :

• Échappement systématique de toute donnée affichée dans render.php, avec esc_html(), esc_attr() ou esc_url() selon le contexte, même pour des attributs typés dans block.json.
• Validation et assainissement de toute donnée en entrée avant enregistrement, notamment pour les blocs qui écrivent en base via une API REST personnalisée.
• Absence d’appel direct à des fichiers PHP en dehors du cycle normal de WordPress, sans vérification defined( 'ABSPATH' ) ou équivalent en tête de fichier.
• Textes visibles correctement internationalisés avec __() ou esc_html__(), en cohérence avec le Text Domain déclaré.

Un plugin rejeté une première fois n’est pas définitivement écarté : l’équipe de revue renvoie généralement une liste précise de points à corriger, et une nouvelle soumission peut être déposée après correction, sans repartir de zéro dans la file d’attente.

Le dépôt SVN, pas Git

Contrairement à une habitude bien ancrée chez la plupart des développeurs, le répertoire WordPress.org fonctionne avec Subversion (SVN), pas Git. Une fois le plugin approuvé, un accès SVN est fourni, avec une structure de dossiers précise à respecter :

svn co https://plugins.svn.wordpress.org/bandeau-alerte-wp-moderne
cd bandeau-alerte-wp-moderne
# Le code va dans /trunk
cp -r ../mon-plugin/* trunk/
svn add trunk/*
svn ci -m "Version initiale 1.0.0"

# Puis un tag correspondant à la version stable
svn cp trunk tags/1.0.0
svn ci -m "Tag de la version 1.0.0"

De nombreuses équipes continuent de développer sur GitHub ou GitLab au quotidien, et ne synchronisent vers SVN qu’au moment de publier une nouvelle version stable, via un script ou une action d’intégration continue dédiée. Cela évite de renoncer au confort de Git pour le travail courant.

Après l’approbation : maintenir le plugin dans la durée

Une fois le plugin en ligne, chaque mise à jour suit le même principe : incrémenter la version dans l’en-tête du plugin et dans le readme.txt, publier le code dans trunk, puis créer un nouveau tag correspondant. Le champ Tested up to mérite d’être tenu à jour à chaque nouvelle version majeure de WordPress, même sans changement de code : il rassure les utilisateurs et influence la visibilité du plugin dans les résultats de recherche du répertoire.

La première revue est la plus longue et la plus exigeante. Une fois le plugin accepté, les mises à jour suivantes ne repassent généralement pas par une revue manuelle complète, sauf changement structurel majeur signalé par l’équipe du répertoire.

En résumé

Publier un bloc sur le répertoire WordPress.org demande une préparation rigoureuse : structure de plugin conforme, readme.txt avec les bons en-têtes, et surtout une attention constante à l’échappement et à la validation des données, points les plus fréquemment relevés lors de la revue de sécurité. Une fois cette première étape franchie, la maintenance via SVN reste simple et prévisible, tag après tag.