Le premier plugin que j'ai mis sur WordPress.org n'a rien expédié pendant neuf jours J'avais commis le code, tagué la version, regardé la mise à jour de la liste avec ma nouvelle description, et dit aux gens qu'il était sorti Les téléchargements sont restés à plat parce que le bouton de téléchargement servait un dossier de tag vide : mon readme.txt dit Stable tag: 1.0.1 et la balise que j'avais réellement créée était 1.0. Rien ne m'a prévenu Le répertoire a fait exactement ce à quoi je lui ai dit.
Cette ligne est le champ aux enjeux les plus élevés d'un plugin WordPress' ;s readme.txt(en), et c'est l'un des nombreux qui échouent tranquillement plutôt que bruyamment Ce guide couvre ce que le répertoire fait avec chaque partie de ce fichier, dans l'ordre où les dégâts ont tendance à se produire Le Générateur WordPress Readme construit le fichier avec ces règles attachées aux champs auxquels ils s'appliquent.
tl;dr :
Stable tagnomme la version que le répertoire sert réellement Il est lu à partir detrunk/readme.txtet il pointe vers un dossier ci-dessous/tags/cela doit exister et doit contenir la version Si elle nomme une version qui n'est pas là, les utilisateurs n'obtiennent rien ; si elle nomme toujours un ancien, ils obtiennent un ancien code peu importe ce que vous avez commis.Tested up tocontrôle l'avertissement de compatibilité sur votre annonce,Tagsindexe uniquement les cinq premiers et la brève description est coupée à 150 caractères.
Que contrôle réellement la balise Stable ?
Un plugin dans le répertoire vit dans Subversion, avec trunk/ pour le développement actuel et tags/<version>/ pour les sorties Quand quelqu'un clique sur Télécharger, le répertoire ne les envoie pas trunk. Cela se lit comme suit trunk/readme.txt, trouve Stable taget sert tags/<that value>/.
Trois conséquences s'ensuivent, et les trois mordent des versions réelles :
- Le readme qui décide que c'est celui du coffre. L'édition du readme dans un dossier de balises ne change rien à ce qui est livré.
- La balise doit exister. un
Stable tagnommer un dossier qui n'a jamais été créé signifie que le téléchargement est vide ou échoue. - Le tronc n'est pas ce que les utilisateurs reçoivent. Vous pouvez vous engager à joncteur toute la semaine ; jusqu'à ce que la balise stable bouge, le code publié est ce que l'ancienne balise contient.
le Manuel du plugin énonce la règle clairement, et il vaut la peine de lire une fois correctement plutôt que de copier un readme d'un autre plugin et d'éditer les champs La seule exception qui mérite d'être connue : Stable tag: trunk signifie " ;serve trunk" ;, ce qui est légal et c'est ainsi qu'une poignée de plugins se libèrent Cela signifie également que chaque validation de trunk est immédiatement en ligne pour chaque utilisateur, c'est pourquoi presque personne ne devrait le faire.
Il y a une seconde moitié dans la version que le readme ne contrôle pas du tout La version dans Stable tag doit correspondre au Version: en-tête dans votre fichier PHP de plugin principal, car c'est à cela qu'un site installé se compare pour décider si une mise à jour existe Expédiez une balise dont l'en-tête du plugin indique toujours le numéro précédent et le répertoire propose une mise à jour qui installe quelque chose qui prétend être la version déjà présente.
Ce que chaque ligne d'en-tête fait à votre annonce
Le bloc d'en-tête est constitué de neuf lignes simples Key: value et chacun d’eux change quelque chose de visible.
| Ligne | Ce qu'il fait | Ce qui ne va pas |
|---|---|---|
Stable tag |
Choisit la version servie | Une mauvaise valeur n’expédie rien ou expédie un ancien code |
Requires at least |
Version minimum WordPress | Des blocs trop élevés installent cela fonctionnerait |
Tested up to |
Déclaration de compatibilité | Tomber derrière montre un " ; non testé" ; avertissement |
Requires PHP |
Version PHP minimale | Trop bas permet aux sites incompatibles d'installer et d'échouer |
Tags |
Mots-clés répertoire | Seuls les cinq premiers sont indexés |
Contributors |
Liens Profils WordPress.org | Une faute de frappe ne crédite silencieusement personne |
Donate link |
Bouton de don de la barre latérale | L'absence est bien, le cassé ne l'est pas |
License / License URI |
La licence | Doit être compatible GPL pour être répertorié |
Tested up to est celui qui coûte les téléchargements en silence Lorsqu'il prend plus de quelques versions principales, la liste affiche un avis indiquant aux visiteurs que le plugin n'est pas testé avec leur version de WordPress, et qu'un plugin qui semble abandonné est moins installé, que cela fonctionne ou non. La mise à jour de cette ligne est un réadme commit to trunk et prend une minute, ce qui est la maintenance la moins chère de l'écosystème.
Tags index cinq. une sixième balise n'est pas une erreur et ne produit aucun avertissement ; c'est simplement du texte mort dans votre fichier Choisissez les cinq personnes qui tapent réellement.
Comment la description est-elle divisée et pourquoi est-elle importante ?
Il y a deux descriptions dans un readme et ils font des travaux différents.
le courte description est le seul bloc de texte entre les lignes d'en-tête et la première == Section ==. Il est plafonné à 150 caractères, et passé que le répertoire le tronque dans les résultats de recherche et sur la carte de plugin, généralement au milieu de phrase C'est la ligne que la plupart des gens lisent avant de décider s'il faut cliquer, ce qui fait de 150 caractères l'immobilier le plus précieux du fichier.
le longue description est le == Description == section et il devient le corps de votre page de listing Il prend un sous-ensemble de Markdown : titres, gras, italique, listes, liens HTML brut est supprimé Les tableaux, blocs de code clôturés avec coloration syntaxique, et le Markdown plus exotique ne s'affichent pas, donc un readme qui a l'air correct dans un prévisualiseur Markdown peut toujours avoir l'air faux sur WordPress.org.
Les autres sections mappent chacune à un onglet sur la liste :
== Description == the main body
== Installation == the Installation tab
== Frequently Asked Questions == the FAQ tab, one "= question =" per entry
== Screenshots == numbered captions, matched to files in /assets/
== Changelog == one "= version =" block per release, newest first
== Upgrade Notice == the short line shown inside wp-admin on update
Upgrade Notice mérite plus d'attention qu'il n'en reçoit habituellement C'est le seul texte que la plupart des utilisateurs voient avant de cliquer sur mise à jour : une ou deux lignes, dans l'invite de mise à jour, expliquant pourquoi cette version compte Un correctif de sécurité, une modification de rupture, une nouvelle exigence PHP Laissé vide, la mise à jour n'est qu'un nombre.
Où vivent la bannière et l'icône ?
Pas dans readme.txt. Cela fait trébucher presque tout le monde la première fois, car c'est de là que vient chaque autre élément de contenu de la liste.
Les images vivent dans un /assets/ répertoire dans SVN, à côté trunk et tagset ils sont appariés par nom de fichier :
| Fichier | intention | Taille |
|---|---|---|
banner-772x250.png |
En-tête d'inscription | 772 x 250 |
banner-1544x500.png |
En-tête Retina | 1544 x 500 |
icon-128x128.png |
Icône des résultats de recherche | 128x128 |
icon-256x256.png |
Icône de rétine | 256x256 |
screenshot-1.png |
Première capture d'écran | n'importe lequel |
Les captures d'écran se connectent à readme par numéro. screenshot-1.png est décrit par la première ligne ci-dessous == Screenshots ==, screenshot-2.png par le second, et ainsi de suite Une légende sans fichier correspondant n'affiche rien ; un fichier sans légende affiche une image non étiquetée.
À quoi ressemble un bon changelog ?
Un bloc par version, le plus récent en haut, chaque ligne indiquant ce qui a changé par rapport à l'utilisateur' ; point de vue :
= 3.2.5 =
* Fixed: admin menu order lost after a role change
* Improved: login customizer previews without saving
= 3.2.4 =
* Added: per-role dashboard widget visibility
" ; Corrections et améliorations de bug" ; ne dit rien à un utilisateur et en dit moins à un critique. Le journal des modifications est également l'endroit où toute personne décidant de faire confiance à votre plugin regarde en premier : une liste stable d'entrées spécifiques se lit comme maintenance, et un intervalle de deux ans se lit comme un abandon, que le code fonctionne toujours ou non.
Les journaux de modifications longs sont prêts à être réduits. Gardez les versions récentes readme.txt et déplacez le reste vers un changelog.txt; le répertoire lit celui coupé et l'historique reste dans le référentiel.
Vérification du fichier avant de l'expédier
Les contrôles mécaniques sont rapides : oui Stable tag faites correspondre un dossier de balise qui existe, correspond-il au Version: dans l'en-tête de votre plugin, est Tested up to actuel, est la courte description sous 150 caractères, y a-t-il cinq balises ou moins.
WordPress.org a un validateur officiel readme cela analyse un fichier et rapporte ce qu'il ne pouvait pas lire, ce qui vaut la peine d'être exécuté une fois par version. Le Générateur Readme prend l'autre direction : il construit le fichier à partir de champs, indique chacune de ces limites à côté du champ auquel il s'applique, prévisualise la liste que le fichier produira et lit un existant readme.txt retour dans le formulaire pour qu'un ancien plugin' ; s fichier puisse être mis à jour sans le retaper.
Si vous regardez d'autres personnes' ; s plugins plutôt que de publier le vôtre, le Détecteur de plugin WordPress répertorie ce qu'une page charge, et le détecteur de thème lit le thème derrière.
