Le readme.txt d’un thème WordPress.org : ce que la revue vérifie

Un client m’a confié un thème maison qu’il voulait proposer gratuitement sur le répertoire officiel, en complément de sa version premium vendue ailleurs. Avant de toucher à la moindre ligne de PHP, j’ai commencé par le readme.txt, parce que c’est le premier fichier que le robot de revue lit, et le premier motif de rejet automatique. Beaucoup de développeurs soignent leur code et bâclent ce fichier texte, en pensant qu’il ne sert qu’à l’affichage sur la page du thème.

C’est une erreur coûteuse : la revue automatisée de WordPress.org analyse la structure du readme.txt avant même d’ouvrir un fichier PHP. Une syntaxe incorrecte, un tag invalide ou une incohérence de version suffit à faire échouer la soumission, avec un message d’erreur parfois assez laconique. Voici la checklist que j’applique désormais avant chaque envoi.

Vérifier l’en-tête obligatoire

Le readme.txt d’un thème suit une convention proche de celle des plugins, mais avec des champs spécifiques. La première ligne doit être === Nom du thème ===, avec exactement trois signes égal de chaque côté, sans espace superflu. Une erreur fréquente consiste à mettre deux égal ou un espace avant le nom : le parseur ne reconnaît alors pas le titre.

• La ligne Contributors: doit lister des identifiants WordPress.org valides, séparés par des virgules, sans espace après le deux-points superflu.
• Requires at least: indique la version minimale de WordPress testée, jamais une version future ou fictive.
• Tested up to: doit correspondre à une version de WordPress réellement sortie au moment de la soumission, pas une version bêta annoncée.
• Requires PHP: est recommandé depuis plusieurs versions du standard, même s’il reste optionnel pour un thème.
• License: et License URI: doivent pointer vers une licence compatible GPL, en général GPLv2 or later.

Les tags : la liste fermée qui piège tout le monde

C’est le point qui fait échouer le plus de soumissions dans mon expérience. Les tags d’un thème WordPress.org ne sont pas libres : ils viennent d’une liste fermée de mots-clés reconnus, répartie en catégories (mise en page, fonctionnalités, sujet). Écrire responsive-design alors que le tag officiel est responsive-layout, ou inventer un tag marketing comme premium-quality, provoque un rejet immédiat de la soumission avec la mention des tags invalides.

Autre piège : le nombre de tags est limité, et certains tags sont mutuellement exclusifs ou réservés à un usage précis (par exemple les tags de couleur ne servent qu’à décrire la palette dominante du thème, pas une ambiance). Je conseille de comparer sa liste de tags à celle d’un thème déjà accepté et proche fonctionnellement, plutôt que d’improviser.

La section Changelog, souvent oubliée

Le readme.txt d’un thème doit contenir une section == Changelog == avec au moins une entrée datée au format = 1.0 = suivie d’une description brève. Un thème soumis sans changelog, ou avec un changelog vide, est rejeté avec un message demandant de documenter l’historique des versions. Ce n’est pas cosmétique : l’équipe de revue s’en sert pour vérifier que le numéro de version dans le style.css correspond bien à la dernière entrée du changelog.

== Changelog ==

= 1.0.1 =
* Correction de l'affichage du menu mobile sur Safari
* Mise à jour de la traduction française

= 1.0 =
* Version initiale

Description longue et capture d’écran

La section == Description == doit rester descriptive et factuelle : pas de superlatifs non vérifiables, pas de comparaison directe avec des thèmes concurrents nommés. La revue humaine qui suit la revue automatique est particulièrement attentive à ce point, mais l’outil automatisé bloque déjà les cas les plus flagrants, comme des liens sortants non liés au thème dans le corps du texte.

Le fichier screenshot.png doit exister à la racine, au format PNG, avec un ratio proche de 4:3 ou 16:9 selon la génération de vérification en vigueur. Une capture manquante ou dans un mauvais format bloque la soumission avant même l’analyse du readme.txt proprement dit.

Cohérence entre style.css et readme.txt

Le numéro de version déclaré dans l’en-tête du style.css doit être strictement identique à celui du Changelog du readme.txt. Une incohérence, même mineure comme un 1.0 contre un 1.0.0, déclenche une alerte. Je vérifie systématiquement ces deux fichiers côte à côte avant l’envoi, avec une recherche rapide en ligne de commande.

grep -i "Version:" style.css
grep -A1 "== Changelog ==" readme.txt

Sur chaque soumission, je traite le readme.txt comme un fichier de configuration à valider, pas comme une notice à rédiger en dernier : dix minutes de vérification évitent souvent un aller-retour de plusieurs jours avec l’équipe de revue.

En résumé

Le readme.txt d’un thème WordPress.org obéit à des règles strictes de format, de tags et de cohérence de version, contrôlées automatiquement avant tout examen du code PHP. Vérifier l’en-tête, choisir des tags dans la liste officielle, tenir un changelog daté et aligner la version avec le style.css élimine la majorité des rejets à ce stade. Le reste, dépôt SVN et revue humaine du code, se joue ensuite, sur un terrain différent.