De eerste plugin die ik op WordPress.org zette, verscheepte negen dagen niets Ik had de code vastgelegd, de release getagd, de listing update bekeken met mijn nieuwe beschrijving, en vertelde mensen dat het uit was Downloads bleven plat omdat de download knop een lege tag map serveerde: mijn readme.txt said Stable tag: 1.0.1 en de tag die ik daadwerkelijk had gemaakt was 1.0. Niets waarschuwde mij. De directory deed precies wat ik hem had opgedragen.
Die regel is het veld met de hoogste inzet in een WordPress-plug-in's readme.txt, en het is een van de vele die stilletjes falen in plaats van luid Deze gids behandelt wat de directory doet met elk deel van dat bestand, in de volgorde waarin de schade de neiging heeft te gebeuren De WordPress Readme Generator bouwt het bestand met deze regels die zijn gekoppeld aan de velden waarop ze van toepassing zijn.
tl;dr:
Stable tagnoemt de versie die de directory daadwerkelijk bedient Het wordt gelezen vantrunk/readme.txt, en het wijst naar een map eronder/tags/dat moet bestaan en moet de release bevatten Als er een versie wordt genoemd die er niet is, krijgen gebruikers niets; als er nog steeds een oude wordt genoemd, krijgen ze oude code, ongeacht wat je hebt begaan.Tested up toregelt de compatibiliteitswaarschuwing op uw vermelding,Tagsindexeert alleen de eerste vijf en de korte beschrijving is teruggebracht tot 150 tekens.
Wat heeft Stable tag eigenlijk te regelen?
Een plug-in in de map leeft in Subversion, met trunk/ voor de huidige ontwikkeling en tags/<version>/ voor releases Wanneer iemand op Downloaden klikt, verzendt de map deze niet trunk. Het luidt trunk/readme.txt, vindt Stable tag, en serveert tags/<that value>/.
Er volgen drie gevolgen en alle drie bijten echte releases:
- De readme die dit beslist is die in kofferbak. Door de readme in een tagmap te bewerken, verandert er niets aan wat er wordt verzonden.
- De tag moet bestaan. a
Stable taghet benoemen van een map die nooit is gemaakt, betekent dat de download leeg is of mislukt. - Trunk is niet wat gebruikers ontvangen. Je kunt je de hele week aan trunk binden; totdat de stabiele tag beweegt, is de vrijgegeven code wat de oude tag ook bevat.
de Plugin Handboek geeft de regel duidelijk weer, en het is de moeite waard om een keer goed te lezen in plaats van een readme van een andere plug-in te kopiëren en de velden te bewerken De enige uitzondering die de moeite waard is om te weten: Stable tag: trunk betekent "serve trunk", wat legaal is en is hoe een handvol plug-ins vrijkomen. Het betekent ook dat elke commit to trunk onmiddellijk live is voor elke gebruiker, en daarom zou bijna niemand het moeten doen.
Er zit een tweede helft aan de release waar de readme helemaal geen controle over heeft De versie in Stable tag moet overeenkomen met de Version: header in uw hoofdplugin PHP-bestand, want dat is waar een geïnstalleerde site zich mee vergelijkt om te beslissen of er een update bestaat Een tag verzenden waarvan de plugin header nog steeds het vorige nummer zegt en de directory biedt een update die iets installeert dat beweert de versie te zijn die al aanwezig is.
Wat elke kopregel doet met uw vermelding
Het headerblok bestaat uit negen lijnen effen Key: value en elk van hen verandert iets zichtbaars.
| Line | Wat het doet | Wat gaat er mis |
|---|---|---|
Stable tag |
Kies de versie die wordt geserveerd | Verkeerde waarde verzendt niets, of verzendt oude code |
Requires at least |
Minimale WordPress-versie | Te hoge blokken installeren dat zou werken |
Tested up to |
Compatibiliteitsverklaring | Achterop vallen toont een "untested" waarschuwing |
Requires PHP |
Minimale PHP-versie | Te laag zorgt ervoor dat incompatibele sites kunnen installeren en mislukken |
Tags |
Directory trefwoorden | Alleen de eerste vijf worden geïndexeerd |
Contributors |
Links WordPress.org profielen | Een typefout vermeldt stilletjes niemand |
Donate link |
Zijbalk doneerknop | Afwezig is prima, gebroken niet |
License / License URI |
De licentie | Moet GPL-compatibel zijn om te worden vermeld |
Tested up to is degene die downloads in stilte kost Wanneer het meer dan een paar kernreleases achterop raakt, toont de lijst een bericht waarin bezoekers wordt verteld dat de plug-in niet is getest met hun versie van WordPress, en een plug-in die er verlaten uitziet, wordt minder geïnstalleerd, ongeacht of deze werkt. Het bijwerken van die regel is een readme commit op trunk en duurt een minuut, wat het goedkoopste onderhoud in het ecosysteem is.
Tags indexeert vijf Een zesde tag is geen fout en geeft geen waarschuwing; het is gewoon dode tekst in je bestand Kies de vijf personen die daadwerkelijk typen.
Hoe is de beschrijving gesplitst, en waarom maakt het uit?
Er zijn twee beschrijvingen in een readme en ze doen verschillende klussen.
de korte beschrijving is het enkele tekstblok tussen de kopregels en het eerste == Section ==. Het is afgedekt op 150 tekens, en vroeger wordt het in de map afgekapt in de zoekresultaten en op de plug-inkaart, meestal halverwege de zin. Dit is de regel die de meeste mensen lezen voordat ze beslissen of ze willen klikken, waardoor 150 tekens het meest waardevolle onroerend goed in het bestand zijn.
de lange beschrijving is de == Description == sectie en het wordt de hoofdtekst van uw pagina met vermeldingen Het neemt een subset van Markdown: koppen, vet, cursief, lijsten, links Ruwe HTML wordt gestript Tabellen, omheinde codeblokken met syntaxisaccentuering en de meer exotische Markdown worden niet weergegeven, dus een leesmij die er goed uitziet in een Markdown-previewer kan er nog steeds verkeerd uitzien op WordPress.org.
De andere secties worden elk toegewezen aan een tabblad op de lijst:
== 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 verdient meer aandacht dan het gewoonlijk krijgt Het is de enige tekst die de meeste gebruikers zien voordat ze op update klikken: een of twee regels, in de update prompt, waarin wordt uitgelegd waarom deze release ertoe doet Een beveiligingsoplossing, een brekende wijziging, een nieuwe PHP-vereiste Leeg gelaten, de update is slechts een getal.
Waar wonen de banner en het icoon?
Niet in readme.txt. Dit struikelt de eerste keer voor bijna iedereen, omdat de readme is waar elk ander stukje advertentie-inhoud vandaan komt.
Beelden leven in een /assets/ map in SVN, naast trunk en tags, en ze worden gekoppeld aan bestandsnaam:
| File | voornemen | Maat |
|---|---|---|
banner-772x250.png |
Lijstkop | 772 x 250 |
banner-1544x500.png |
Retina-header | 1544 x 500 |
icon-128x128.png |
Pictogram voor zoekresultaten | 128 x 128 |
icon-256x256.png |
Retina pictogram | 256 x 256 |
screenshot-1.png |
Eerste screenshot | elk |
De screenshots sluiten op nummer terug op de readme. screenshot-1.png wordt beschreven door de eerste regel onder == Screenshots ==, screenshot-2.png bij de tweede, enzovoort Een bijschrift zonder overeenstemmend bestand toont niets; een bestand zonder bijschrift toont een afbeelding zonder label.
Hoe ziet een goede changelog eruit?
Eén blok per release, de nieuwste bovenaan, waarbij elke regel zegt wat er is veranderd vanuit het oogpunt van de gebruiker's:
= 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
"Bug fixes en verbeteringen" vertelt een gebruiker niets en vertelt een recensent minder De changelog is ook waar iedereen die besluit of hij uw plugin vertrouwt als eerste kijkt: een vaste lijst met specifieke vermeldingen leest als onderhoud, en een gat van twee jaar leest als verlatenheid of de code nog werkt of niet.
Lange changelogs zijn prima te trimmen Houd de recente releases binnen readme.txt en verplaats de rest naar een changelog.txt; de map leest de bijgesneden map en de geschiedenis blijft in de repository.
Controle van het bestand voordat u het verzendt
De mechanische controles zijn snel: doet Stable tag match een tagmap die bestaat, komt deze overeen met de Version: in uw plug-inheader staat Tested up to actueel, is de korte beschrijving onder 150 tekens, zijn er vijf tags of minder.
WordPress.org heeft een officiële readme validator dat parseert een bestand en rapporteert wat het niet kon lezen, wat de moeite waard is om één keer per release te draaien De Readme Generator neemt de andere richting: het bouwt het bestand op vanuit velden, vermeldt elk van deze limieten naast het veld waarop het van toepassing is, geeft een voorbeeld van de lijst die het bestand zal produceren en leest een bestaand bestand readme.txt terug in het formulier, zodat een oude plug-in' s-bestand kan worden bijgewerkt zonder het opnieuw te typen.
Als u naar andere mensen kijkt's plug-ins in plaats van uw eigen plug-ins te publiceren, de WordPress Plugin Detector geeft aan wat een pagina laadt, en de themadetector leest het thema erachter.
