Il primo plugin che ho messo su WordPress.org non ha spedito nulla per nove giorni Avevo impegnato il codice, taggato il rilascio, guardato l'aggiornamento dell'elenco con la mia nuova descrizione e detto alle persone che era fuori I download sono rimasti piatti perché il pulsante di download serviva una cartella di tag vuota: la mia readme.txt detto Stable tag: 1.0.1 e il tag che avevo effettivamente creato era 1.0. Niente mi ha avvertito La directory ha fatto esattamente quello che le ho detto.
Quella linea è il campo con la posta in gioco più alta in un plugin WordPress's readme.txt, ed è uno dei tanti che falliscono in silenzio piuttosto che ad alta voce Questa guida copre ciò che la directory fa con ogni parte di quel file, nell'ordine in cui il danno tende ad accadere Il Generatore di Readme WordPress costruisce il file con queste regole allegate ai campi a cui si applicano.
tl; dr:
Stable tagnomina la versione effettivamente servita dalla directory Viene letta datrunk/readme.txte punta a una cartella sotto/tags/che deve esistere e deve contenere la versione Se nomina una versione che non c'è, gli utenti non ottengono nulla; se ancora nomina un vecchio, ottengono il vecchio codice non importa quello che hai commesso.Tested up tocontrolla l'avviso di compatibilità sulla tua inserzione,Tagsindicizza solo i primi cinque e la breve descrizione è tagliata a 150 caratteri.
Cosa controlla effettivamente Stable tag?
Un plugin nella directory vive in Subversion, con trunk/ per lo sviluppo attuale e tags/<version>/ per le versioni Quando qualcuno fa clic su Scarica, la directory non le invia trunk. Si legge trunk/readme.txt, trova Stable tag, e serve tags/<that value>/.
Seguono tre conseguenze e tutte e tre mordono i rilasci reali:
- Il readme che decide questo è quello in tronco. La modifica del readme all'interno di una cartella di tag non cambia nulla su ciò che viene spedito.
- Il tag deve esistere. un'
Stable tagnominare una cartella che non è mai stata creata significa che il download è vuoto o non riesce. - Trunk non è ciò che ricevono gli utenti. Puoi impegnarti a trunk tutta la settimana; finché il tag stabile non si muove, il codice rilasciato è quello che contiene il vecchio tag.
la Manuale del plugin afferma la regola in modo chiaro, e vale la pena leggere una volta correttamente piuttosto che copiare un readme da un altro plugin e modificare i campi L'unica eccezione che vale la pena conoscere: Stable tag: trunk significa che & quot;serve trunk", che è legale ed è il modo in cui una manciata di plugin rilasciano Significa anche che ogni commit in trunk è immediatamente attivo per ogni utente, motivo per cui quasi nessuno dovrebbe farlo.
C'è una seconda metà della release che il readme non controlla affatto La versione in Stable tag deve corrispondere al Version: intestazione nel tuo file PHP del plugin principale, perché è ciò che un sito installato confronta contro per decidere se esiste un aggiornamento Spedisci un tag la cui intestazione del plugin dice ancora il numero precedente e la directory offre un aggiornamento che installa qualcosa che afferma di essere la versione già presente.
Cosa fa ogni riga di intestazione al tuo elenco
Il blocco di intestazione è composto da nove righe di pianura Key: value e ognuno di loro cambia qualcosa di visibile.
| Linea | Quello che fa | Cosa va storto |
|---|---|---|
Stable tag |
Sceglie la versione servita | Il valore sbagliato non spedisce nulla o spedisce il vecchio codice |
Requires at least |
Versione minima WordPress | Blocchi troppo alti installa che funzionerebbero |
Tested up to |
Dichiarazione di compatibilità | Cadere dietro mostra un & quot;untested" avvertimento |
Requires PHP |
Versione minima PHP | Troppo basso consente ai siti incompatibili di installarsi e fallire |
Tags |
Parole chiave della directory | Solo i primi cinque sono indicizzati |
Contributors |
Collegamenti Profili WordPress.org | Un errore di battitura non accredita silenziosamente nessuno |
Donate link |
Pulsante di donazione della barra laterale | Assente va bene, rotto non è |
License / License URI |
La licenza | Deve essere compatibile con GPL per essere elencato |
Tested up to è quello che costa i download in silenzio Quando rimane indietro di più di qualche versione principale, l'elenco mostra un avviso che dice ai visitatori che il plugin non è testato con la loro versione di WordPress e un plugin che sembra abbandonato viene installato meno indipendentemente dal fatto che funzioni. L'aggiornamento di quella riga è un readme commit to trunk e richiede un minuto, che è la manutenzione più economica dell'ecosistema.
Tags indici cinque Un sesto tag non è un errore e non produce alcun avviso; è semplicemente testo morto nel tuo file Scegli le cinque persone effettivamente digita.
Come è divisa la descrizione, e perché ha importanza?
Ci sono due descrizioni in un readme e fanno lavori diversi.
la breve descrizione è il singolo blocco di testo tra le righe di intestazione e la prima == Section ==. È limitato a 150 caratteri, e passato che la directory lo tronca nei risultati di ricerca e sulla scheda plugin, di solito a metà frase Questa è la riga che la maggior parte delle persone legge prima di decidere se fare clic, il che rende 150 caratteri il bene immobile più prezioso nel file.
la descrizione lunga è il == Description == sezione e diventa il corpo della tua pagina di inserzione Prende un sottoinsieme di Markdown: intestazioni, grassetto, corsivo, elenchi, collegamenti HTML grezzo è spogliato Tabelle, blocchi di codice recintati con evidenziazione della sintassi e il più esotico Markdown non rendono, quindi un readme che sembra giusto in un visualizzatore di Markdown può ancora sembrare sbagliato su WordPress.org.
Ciascuna delle altre sezioni viene mappata su una scheda nell'elenco:
== 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 merita più attenzione di quella che ottiene di solito È l'unico testo che la maggior parte degli utenti vede prima di cliccare su aggiornamento: una o due righe, nel prompt di aggiornamento, che spiega perché questa release è importante Una correzione di sicurezza, una modifica di rottura, un nuovo requisito PHP Lasciato vuoto, l'aggiornamento è solo un numero.
Dove vivono il banner e l'icona?
Non dentro readme.txt. Questo fa inciampare quasi tutti la prima volta, perché il readme è da dove proviene ogni altro contenuto dell'elenco.
Immagini vivono in un /assets/ directory in SVN, accanto trunk e tags, e sono abbinati per nome file:
| File | proposito | Dimensione |
|---|---|---|
banner-772x250.png |
Intestazione dell'elenco | 772x250 |
banner-1544x500.png |
Intestazione Retina | 1544x500 |
icon-128x128.png |
Icona risultati ricerca | 128x128 |
icon-256x256.png |
Icona Retina | 256x256 |
screenshot-1.png |
Primo screenshot | un po' di |
Gli screenshot si ricollegano al readme per numero. screenshot-1.png è descritto dalla prima riga sotto == Screenshots ==, screenshot-2.png dal secondo, e così via Una didascalia senza file corrispondente non mostra nulla; un file senza didascalia mostra un'immagine senza etichetta.
Che aspetto ha un buon registro delle modifiche?
Un blocco per versione, il più recente in alto, ogni riga dice cosa è cambiato dall'utente's punto di vista:
= 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
& quot; Correzioni di bug e miglioramenti" non dice nulla a un utente e dice meno a un recensore Il registro delle modifiche è anche il luogo in cui chiunque decida se fidarsi del tuo plugin guarda per primo: un elenco costante di voci specifiche si legge come manutenzione e un intervallo di due anni si legge come abbandono indipendentemente dal fatto che il codice funzioni ancora o meno.
I changelog lunghi vanno bene da tagliare Mantenere le versioni recenti in readme.txt e sposta il resto su a changelog.txt; la directory legge quella ritagliata e la cronologia rimane nel repository.
Controllo del file prima di spedirlo
I controlli meccanici sono rapidi: fa Stable tag abbina una cartella di tag esistente, corrisponde a Version: nell'intestazione del tuo plugin, è Tested up to attuale, è la breve descrizione sotto 150 caratteri, ci sono cinque tag o meno.
WordPress.org ha un validatore ufficiale readme che analizza un file e riporta ciò che non è stato possibile leggere, che vale la pena eseguire una volta per rilascio Il Generatore Readme prende l'altra direzione: costruisce il file dai campi, indica ciascuno di questi limiti accanto al campo a cui si applica, visualizza in anteprima l'elenco che il file produrrà e legge un esistente readme.txt torna nel modulo in modo che un vecchio plugin's file può essere aggiornato senza ridigitarlo.
Se stai guardando altre persone's plugin piuttosto che pubblicare il tuo, il Rilevatore di plugin WordPress elenca ciò che carica una pagina e il rilevatore tema legge il tema dietro di esso.
