readme.txt, nagłówek wtyczki i SVN: jak czyta je WordPress.org

Wtyczkę w katalogu WordPress.org opisują dwa źródła tekstowe, które odpowiadają na różne pytania. Komentarz nagłówkowy na początku głównego pliku PHP czyta sam WordPress i katalog, a plik readme.txt czyta wyłącznie katalog. Które z tych źródeł jest rozstrzygające, nie jest oczywiste: przycisk pobierania pokazuje wersję z nagłówka, jednozdaniowy opis pod nazwą wtyczki pochodzi z readme, a pole „Requires at least” może występować w obu plikach. Do tego repozytorium SVN decyduje, która kopia readme w ogóle zostanie odczytana.

Artykuł omawia oba pliki na kompletnych przykładach, na podstawie kodu importu katalogu wyjaśnia, które pole wygrywa przy sprzeczności, opisuje układ trunk/, tags/ i assets/ wraz z pełną sekwencją poleceń oraz zestawia błędy zgłaszane przez walidator readme i importer. Przegląd wtyczek i Plugin Check to tematy osobnych artykułów tej serii.

Nagłówek wtyczki w pliku głównym

WordPress rozpoznaje wtyczkę po bloku komentarza, który zawiera co najmniej wiersz Plugin Name:. Pozostałe pola są opcjonalne, ale kilka z nich analizuje katalog. Podczas importu wydania przeszukuje on pliki PHP w katalogu głównym opublikowanego folderu i bierze pierwszy plik, którego nagłówek zawiera nazwę wtyczki. Dlatego podręcznik wtyczek wymaga, by plik główny leżał bezpośrednio w trunk/: ścieżka w rodzaju trunk/my-plugin/my-plugin.php psuje pobieranie. Podfoldery na dołączane pliki nie stanowią problemu.

Poniższy plik główny jest kompletny i da się go od razu aktywować. Należy do małej przykładowej wtyczki „LW Reading Time”, która towarzyszy całemu artykułowi:

<?php
/**
 * Plugin Name:       LW Reading Time
 * Plugin URI:        https://lukaswojcik.com/plugins/lw-reading-time/
 * Description:       Shows the estimated reading time above single posts.
 * Version:           1.2.0
 * Requires at least: 6.5
 * Requires PHP:      7.4
 * Author:            Lukas Wojcik
 * Author URI:        https://lukaswojcik.com/
 * License:           GPLv2 or later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       lw-reading-time
 *
 * @package LW_Reading_Time
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Prepends the estimated reading time to the content of single posts.
 *
 * @param string $content Post content.
 * @return string Filtered content.
 */
function lw_reading_time_prepend( $content ) {
	if ( ! is_singular( 'post' ) || ! in_the_loop() || ! is_main_query() ) {
		return $content;
	}

	$words   = str_word_count( wp_strip_all_tags( $content ) );
	$minutes = max( 1, (int) ceil( $words / 200 ) );

	$label = sprintf(
		/* translators: %d: number of minutes. */
		_n( '%d minute read', '%d minutes read', $minutes, 'lw-reading-time' ),
		$minutes
	);

	return '<p class="lw-reading-time">' . esc_html( $label ) . '</p>' . $content;
}
add_filter( 'the_content', 'lw_reading_time_prepend' );

Kilka pól zasługuje na bliższe spojrzenie:

• Version jest porównywane funkcją PHP version_compare(), więc 1.02 jest „większe” niż 1.1. Importer ostrzega przed wszystkim poza cyframi, kropkami i opcjonalnym przyrostkiem -rc, -beta lub -alpha, a wersje, które byłyby niebezpieczne jako ścieżka folderu, odrzuca.
• Requires at least i Requires PHP to wymagania dotyczące wersji, które sam WordPress sprawdza przy aktywacji; od WordPressa 6.5 sprawdza też Requires Plugins. Od WordPressa 5.8 readme nie jest już do tego analizowane; funkcja validate_plugin_requirements() w rdzeniu czyta wyłącznie nagłówek przez get_plugin_data().
• Description pojawia się na liście wtyczek w panelu (według podręcznika poniżej 140 znaków); w katalogu służy tylko jako wartość zastępcza.
• Requires Plugins (od WordPressa 6.5) przyjmuje rozdzieloną przecinkami listę slugów z katalogu, np. woocommerce, a nie ścieżki typu my-plugin/my-plugin.php. Wtyczki hostowane na WordPress.org mogą zależeć tylko od wtyczek również tam hostowanych. Jeśli sluga nie da się przypisać do opublikowanej wtyczki, importer przerywa wydanie.
• Update URI nie należy do wtyczki z katalogu. Importer akceptuje to pole tylko wtedy, gdy wskazuje własny adres wordpress.org/plugins/<slug>, a w innym przypadku przerywa import.
• Text Domain odpowiada slugowi; tłumaczenia to temat osobnego artykułu tej serii.

Plik readme.txt: pola nagłówka, krótki opis, sekcje

Readme korzysta z dostosowanej odmiany Markdown z nagłówkami w ==. Kompletne readme przykładowej wtyczki wygląda tak:

=== LW Reading Time ===
Contributors: lukaswojcik
Tags: reading time, posts, content
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.2.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Shows the estimated reading time above single posts, based on the word count of the post content.

== Description ==

LW Reading Time counts the words of a post and shows the estimated reading time above the content of single posts.

* No settings page, no database tables.
* The output is a single paragraph with the class `lw-reading-time`.
* Translations are managed on translate.wordpress.org.

== Installation ==

1. Install the plugin via Plugins > Add New, or upload the folder `lw-reading-time` to `/wp-content/plugins/`.
2. Activate the plugin.
3. Open any single post; the reading time appears above the content.

== Frequently Asked Questions ==

= How is the reading time calculated? =

The word count of the post content is divided by 200 and rounded up to full minutes.

= Does the plugin change pages? =

No. Only single posts of the post type `post` are changed.

== Screenshots ==

1. Reading time above a single post.
2. The same post with the Polish translation active.

== Changelog ==

= 1.2.0 =
* Plural forms for the reading time label.
* WordPress 6.5 or later is required.

= 1.1.0 =
* Output limited to the main query.

== Upgrade Notice ==

= 1.2.0 =
Adds plural forms. WordPress 6.5 or later is now required.

Pola nagłówka

• Contributors musi zawierać nazwy użytkowników WordPress.org. Parser usuwa początkowe @, szuka każdego wpisu najpierw jako loginu, a potem jako sluga profilu, i z ostrzeżeniem odrzuca to, czego nie znajdzie. Podręcznik określa tę listę jako wrażliwą na wielkość liter.
• Tags przyjmuje najwyżej pięć pojęć, reszta jest pomijana z ostrzeżeniem. Tagi plugin i wordpress znikają całkowicie, a walidator odnotowuje tagi używane przez mniej niż pięć wtyczek. Nazwy konkurencyjnych wtyczek jako tagi są według podręcznika niedozwolone.
• Tested up to powinno zawierać wyłącznie liczby, np. 7.1. Katalog ignoruje wersje poprawkowe i sam dopisuje aktualną; dlatego strona Plugin Check pokazuje obecnie „Tested up to 7.0.6”. Wartości wyższe o więcej niż jedną wersję główną od bieżącej gałęzi stabilnej parser odrzuca: przy WordPressie 7.1.2 jako aktualnym wydaniu w dniu 29.09.2026 7.2 zostanie przyjęte, a 7.3 już nie.
• Requires PHP musi mieć postać x.y lub x.y.z, w przeciwnym razie wartość jest ignorowana z ostrzeżeniem.
• License jest porównywane z listami słów kluczowych. Określenia takie jak „NonCommercial” czy „proprietary” dają w walidatorze błąd, nieznana licencja tylko uwagę.
• Stable tag steruje całym mechanizmem SVN i ma poniżej własną sekcję.

Krótki opis i sekcje

Tekst po polach nagłówka aż do pierwszego nagłówka sekcji to krótki opis, czyli wiersz tuż pod nazwą wtyczki; kilka wierszy lub akapitów parser łączy w jeden. Parser dopuszcza 150 znaków liczonych po usunięciu Markdown i HTML. Dłuższy tekst zostaje ucięty na kropce w ostatniej jednej piątej limitu, a jeśli jej brak, z wielokropkiem; walidator zgłasza wtedy ostrzeżenie. Gdy wiersza brakuje, jego miejsce zajmuje pierwszy wiersz opisu.

Oczekiwane sekcje to Description, Installation, Frequently Asked Questions, Screenshots, Changelog i Upgrade Notice. Nieznane sekcje nie przepadają, lecz trafiają na koniec opisu ze swoim tytułem jako śródtytułem. Każda sekcja jest ograniczona do 2500 słów, FAQ i changelog do 5000; dłuższy tekst zostaje skrócony. Wpisy FAQ w formie = Pytanie = stają się na stronie wtyczki listą definicji, a numerowane wiersze pod Screenshots zamieniają się w podpisy plików screenshot-1, screenshot-2 i kolejnych. Podręcznik ostrzega, że pliki readme większe niż 10 kB mogą powodować błędy, i zaleca przeniesienie starszych wpisów changelogu do osobnego pliku changelog.txt.

Upgrade Notice nie jest zakładką na stronie wtyczki. Importer zapisuje tę sekcję osobno, API katalogu ją dostarcza, a WordPress wyświetla ją jako zwykły tekst na ekranie Kokpit → Aktualizacje obok oczekującej aktualizacji. Oficjalne przykładowe readme zaleca najwyżej 300 znaków; parser tego limitu nie egzekwuje.

Która wartość wygrywa, gdy nagłówek i readme się różnią

Podręcznik mówi tylko ogólnie, że wersja pochodzi z pliku głównego, a reszta z readme. Kod importu katalogu jest dokładniejszy. Tabela zestawia jego zachowanie według stanu na 29.09.2026:

„Poprawnie sformatowany” oznacza co najmniej trzy znaki złożone z cyfr i kropek. Wiersz „Tested up to” łatwo przeoczyć: importer rejestruje Tested up to jako dodatkowe pole nagłówka pliku głównego, więc wartość w nim zapisana nadpisuje readme, a Plugin Check zgłasza rozbieżność między nimi. Ponieważ rdzeń czyta wymagania wyłącznie z nagłówka, wartości wymagań warto utrzymywać identyczne w obu plikach.

Układ SVN: trunk, tags i assets

Po zatwierdzeniu każda wtyczka dostaje repozytorium pod adresem https://plugins.svn.wordpress.org/<slug> z trzema folderami: trunk/ na bieżący kod, tags/ na wydania i assets/ na grafiki oraz blueprint. Folder branches/ nie jest już tworzony. Podręcznik traktuje SVN jako repozytorium wydań: każdy commit od nowa buduje pliki ZIP wszystkich wersji, co jest jednym z powodów, dla których zmiany mogą pojawiać się nawet po sześciu godzinach.

Jak Stable tag wybiera kod

Import zaczyna się od trunk/readme.txt i odczytuje z niego tylko jeden wiersz: Stable tag. Przy Stable tag: 1.2.0 katalog szuka folderu tags/1.2.0/. Jeśli folder istnieje i zawiera pliki, wszystko inne pochodzi stamtąd: wyświetlane readme, nagłówek wtyczki i plik ZIP dla użytkowników. Zmiany opisu w trunk/readme.txt nie mają wpływu na stronę, dopóki tag istnieje. Również readme wewnątrz tagu musi zawierać poprawny Stable tag; w przeciwnym razie, według podręcznika, wtyczka może przestać się aktualizować.

Nazwa folderu wybiera kod, ale nie ustala wersji. Wersja na przycisku pobierania pochodzi z nagłówka Version w otagowanym pliku głównym. Jeśli w tags/1.4/ nadal widnieje Version: 1.3, strona pokazuje 1.3, a importer zgłasza niezgodność nagłówka z tagiem. Cudzysłowy wokół wartości Stable tag i przedrostek tags/ parser usuwa.

Assets: nazwy, rozmiary i blueprint

Wszystko w assets/ dotyczy wszystkich wersji i nie trafia do pliku ZIP. Grafiki w trunk/assets/ albo tags/1.0/assets/ nie są używane. Nazwy plików są stałe:

Wymiary w pikselach muszą zgadzać się z nazwami, a baner w wysokiej rozdzielczości działa tylko jako uzupełnienie zwykłego. Nazwy plików muszą być pisane małymi literami. Banery i zrzuty ekranu da się lokalizować przyrostkami takimi jak -de, banery także przyrostkiem -rtl. Z powodu buforowania w CDN nowe grafiki mogą pojawić się dopiero po sześciu godzinach.

W przypadku blueprintu importer przyjmuje tylko poprawny JSON i dopisuje krok installPlugin z aktywacją, jeśli plik sam nie instaluje wtyczki. Przycisk podglądu widzą wyłącznie committerzy, dopóki któryś z nich nie przełączy podglądu na publiczny w widoku Advanced wtyczki. Tworzenie blueprintu opisuje artykuł o Playground i Blueprints w tej serii.

Pełna sekwencja poleceń dla pierwszego wydania i aktualizacji

Nazwą użytkownika SVN jest nazwa użytkownika WordPress.org, a nie adres e-mail, przy czym wielkość liter ma znaczenie. Osobne hasło do SVN da się ustawić w profilu na WordPress.org. Poniższa sekwencja obejmuje pierwsze wydanie wersji 1.2.0 wraz z assets:

# First release: check out the repository created after approval.
svn co https://plugins.svn.wordpress.org/lw-reading-time lw-reading-time-svn
cd lw-reading-time-svn

# Main plugin file and readme.txt go directly into trunk/, not into a subfolder.
cp ../lw-reading-time/lw-reading-time.php ../lw-reading-time/readme.txt trunk/
svn add trunk/*

# Banner, icon, screenshots and blueprint go into the top-level assets/ folder.
cp ../lw-reading-time-assets/banner-772x250.png ../lw-reading-time-assets/banner-1544x500.png assets/
cp ../lw-reading-time-assets/icon-128x128.png ../lw-reading-time-assets/icon-256x256.png assets/
cp ../lw-reading-time-assets/screenshot-1.png ../lw-reading-time-assets/screenshot-2.png assets/
mkdir assets/blueprints
cp ../lw-reading-time-assets/blueprint.json assets/blueprints/
svn add assets/*

# Serve the images as images instead of application/octet-stream.
svn propset svn:mime-type image/png assets/*.png

# The username is case sensitive.
svn ci -m "Add LW Reading Time 1.2.0 to trunk, add assets" --username WPORG_USERNAME

# Tag the release from trunk and commit the tag.
svn cp trunk tags/1.2.0
svn ci -m "Tag version 1.2.0"

Między oboma commitami Stable tag wskazuje tag, który jeszcze nie istnieje, więc katalog na chwilę wraca do trunk/; podręcznik opisuje to jako nieszkodliwe. Wiersz z svn propset to udokumentowane rozwiązanie sytuacji, w której przeglądarka pobiera grafiki zamiast je wyświetlać; dla plików JPEG właściwym typem jest image/jpeg.

Przy każdym kolejnym wydaniu podręcznik zaleca najpierw zmienić trunk/ łącznie z nowym Stable tag, potem skopiować trunk do nowego tagu poleceniem svn cp i zatwierdzić oba w jednym commicie:

# Next release: bring the working copy up to date.
cd lw-reading-time-svn
svn up

# Version header and Stable tag both say 1.3.0 in the copied files.
cp ../lw-reading-time/lw-reading-time.php ../lw-reading-time/readme.txt trunk/
svn add --force trunk
svn stat
svn diff

# Copy trunk to the new tag and commit trunk and tag together.
svn cp trunk tags/1.3.0
svn ci -m "Release 1.3.0"

Ponieważ svn cp działa w kopii roboczej, historia zostaje zachowana, a tag dostaje dokładnie pliki z trunk/, łącznie z readme zawierającym właściwy Stable tag. Wszystko, co trafi do commita, ląduje na stronach użytkowników, także .gitignore; archiwa ZIP w ogóle nie należą do SVN.

Typowe błędy i walidator readme

Większość problemów po wydaniu wynika z kilku przyczyn:

• Stable tag wskazuje nieistniejący tag. Importer z ostrzeżeniem wraca do trunk/, a użytkownicy dostają to, co akurat leży w trunk, być może niedokończony kod.
• Stable tag: trunk. To nadal działa, ale podręcznik uznaje takie ustawienie za nieobsługiwane i zabrania go w nowych wtyczkach. Walidator oznacza każdy Stable tag zawierający „trunk”, a przy włączonym potwierdzaniu wydań importer odrzuca wydanie z trunk.
• Tag utworzony, nagłówek niezmieniony. Strona nadal pokazuje starą wersję, a importer zgłasza niezgodność nagłówka Version z tagiem.
• Readme zmienione tylko w trunk. Dopóki Stable tag wskazuje istniejący tag, zmiana się nie pojawi.
• Błędne nazwy assets. Własne rozmiary banerów, nazwy pisane wielkimi literami albo assets w trunk/ są ignorowane.
• Zależności spoza katalogu. Slug w Requires Plugins, który nie jest opublikowaną wtyczką z katalogu, zatrzymuje import.

Walidator readme pod adresem wordpress.org/plugins/developers/readme-validator/ korzysta z tego samego parsera co katalog. Przyjmuje wklejony tekst albo adres URL w domenach plugins.svn.wordpress.org, themes.svn.wordpress.org lub raw.githubusercontent.com do 512 kB. Błędy to m.in. brakująca albo pozostawiona jako szablon nazwa, np. dosłowne === Plugin Name ===, znak towarowy w nazwie i niezgodna licencja. Ostrzeżenia dotyczą nieprawidłowego Stable tag, brakującego lub pominiętego „Tested up to”, odrzuconych Contributors, nadmiarowych tagów i skróconego tekstu. Uwagi wymieniają brakujące elementy opcjonalne, takie jak FAQ, changelog czy zrzuty ekranu. Walidator widzi wyłącznie readme; istnienie tagu, zgodność wersji i rozwiązywalność zależności sprawdza dopiero import.

Ograniczenia i otwarte kwestie

Stwierdzenia o pierwszeństwie pól opierają się na kodzie źródłowym katalogu w lustrzanym repozytorium meta na GitHubie według stanu na 29.09.2026. Ten kod często się zmienia; sama klasa importu dostała we wrześniu 2026 kilka commitów. Zachowanie może się więc zmienić bez aktualizacji podręcznika.

Kilka kwestii pozostaje otwartych. Zdanie z podręcznika, że readme nie jest już analizowane pod kątem wymagań, dotyczy rdzenia WordPressa; katalog nadal traktuje wartości z readme jako zastępcze. Nie prześledzono, który wpis Upgrade Notice API aktualizacji wybiera dla konkretnej aktualizacji. Nie sprawdzono też, jak ściśle wyszukiwanie Contributors traktuje wielkość liter.

Polecenia dotyczące typu MIME są udokumentowane tylko dla PNG i JPEG, nie dla ikon SVG. Wartość 10 kB dla readme to raczej ogólne ostrzeżenie niż twardy limit.

Przykładowa wtyczka nie została zgłoszona do katalogu. Na instalacji testowej z WordPressem 7.1.2 aktywuje się bez komunikatów, a Plugin Check 2.1.0 nie zgłasza dla niej błędów. Obie sekwencje poleceń SVN przeszły bez błędów na lokalnym repozytorium. Opisane zachowanie walidatora wynika z jego kodu źródłowego.