readme.txt, Plugin-Header und SVN: wie WordPress.org sie liest

Ein Plugin im Verzeichnis von WordPress.org wird durch zwei Textquellen beschrieben, die unterschiedliche Fragen beantworten. Den Kommentar-Header oben in der PHP-Hauptdatei lesen WordPress selbst und das Verzeichnis, die readme.txt liest nur das Verzeichnis. Welche der beiden Quellen gilt, ist auf den ersten Blick nicht klar: Der Download-Button zeigt die Version aus dem Header, die Kurzbeschreibung unter dem Plugin-Namen stammt aus der Readme, und für „Requires at least“ dürfen beide Dateien einen Wert enthalten. Dazu kommt, dass das SVN-Repository darüber entscheidet, welche Kopie der Readme überhaupt gelesen wird.

Dieser Beitrag geht beide Dateien mit vollständigen Beispielen durch, klärt anhand des Import-Codes des Verzeichnisses, welches Feld bei Widerspruch gewinnt, erklärt den Aufbau aus trunk/, tags/ und assets/ mit einer kompletten Befehlsfolge und listet die Fehler, die Readme-Validator und Importer melden. Review und Plugin Check behandeln eigene Beiträge dieser Reihe.

Der Plugin-Header in der Hauptdatei

WordPress erkennt ein Plugin an einem Kommentarblock, der mindestens die Zeile Plugin Name: enthält. Alle weiteren Felder sind optional, mehrere davon wertet aber das Verzeichnis aus. Beim Import einer Version durchsucht es die PHP-Dateien im Wurzelverzeichnis des veröffentlichten Ordners und nimmt die erste Datei, deren Header einen Plugin-Namen trägt. Deshalb verlangt das Plugin-Handbuch, dass die Hauptdatei direkt in trunk/ liegt: Ein Pfad wie trunk/my-plugin/my-plugin.php macht die Downloads kaputt. Unterordner für eingebundene Dateien sind dagegen kein Problem.

Die folgende Hauptdatei ist vollständig und lässt sich so aktivieren; das kleine Beispiel-Plugin „LW Reading Time“ begleitet den ganzen Beitrag:

<?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' );

Einige Felder verdienen einen genaueren Blick:

• Version wird mit PHPs version_compare() verglichen; 1.02 gilt daher als größer als 1.1. Der Importer warnt bei allem außer Ziffern, Punkten und einem optionalen Suffix -rc, -beta oder -alpha und lehnt Versionsangaben ab, die als Ordnerpfad unsicher wären.
• Requires at least und Requires PHP sind die Versionsanforderungen, die WordPress selbst bei der Aktivierung prüft; seit WordPress 6.5 prüft es außerdem Requires Plugins. Seit WordPress 5.8 wird die Readme dafür nicht mehr ausgewertet; validate_plugin_requirements() im Core liest ausschließlich den Header über get_plugin_data().
• Description erscheint in der Plugin-Liste im Backend (laut Handbuch unter 140 Zeichen); im Verzeichnis dient sie nur als Ersatz.
• Requires Plugins (seit WordPress 6.5) erwartet eine kommagetrennte Liste von Verzeichnis-Slugs wie woocommerce, keine Pfade wie my-plugin/my-plugin.php. Plugins auf WordPress.org dürfen nur von Plugins abhängen, die ebenfalls dort liegen. Lässt sich ein Slug keinem veröffentlichten Plugin zuordnen, bricht der Importer die Version ab.
• Update URI gehört nicht in ein Verzeichnis-Plugin. Der Importer akzeptiert das Feld nur, wenn es auf die eigene Adresse unter wordpress.org/plugins/<slug> zeigt, und bricht sonst ab.
• Text Domain entspricht dem Slug; Übersetzungen sind Thema eines eigenen Beitrags dieser Reihe.

Die readme.txt: Kopffelder, Kurzbeschreibung, Abschnitte

Die Readme nutzt einen angepassten Markdown-Dialekt mit Überschriften in ==. Eine vollständige Readme für das Beispiel-Plugin sieht so aus:

=== 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.

Kopffelder

• Contributors muss Benutzernamen von WordPress.org enthalten. Der Parser entfernt ein führendes @, sucht jeden Eintrag zuerst als Login-Namen und dann als Profil-Slug und verwirft mit einer Warnung alles, was er nicht findet. Das Handbuch bezeichnet die Liste als groß- und kleinschreibungssensitiv.
• Tags nimmt höchstens fünf Begriffe auf, der Rest wird mit Warnung ignoriert. Die Tags plugin und wordpress fallen ganz weg, und der Validator vermerkt Tags, die weniger als fünf Plugins nutzen. Namen von Konkurrenz-Plugins sind laut Handbuch als Tags nicht erlaubt.
• Tested up to soll nur Zahlen enthalten, etwa 7.1. Das Verzeichnis ignoriert Unterversionen und ergänzt die aktuelle selbst; deshalb zeigt die Seite von Plugin Check derzeit „Tested up to 7.0.6“. Werte, die mehr als eine Hauptversion über dem aktuellen stabilen Zweig liegen, verwirft der Parser: Mit WordPress 7.1.2 als aktueller Version am 29.09.2026 wird 7.2 angenommen, 7.3 nicht.
• Requires PHP muss die Form x.y oder x.y.z haben, sonst wird der Wert mit Warnung ignoriert.
• License wird gegen Schlagwortlisten geprüft. Begriffe wie „NonCommercial“ oder „proprietary“ führen im Validator zu einem Fehler, eine unbekannte Lizenz nur zu einem Hinweis.
• Stable tag steuert den gesamten SVN-Mechanismus und bekommt unten einen eigenen Abschnitt.

Kurzbeschreibung und Abschnitte

Der Text nach den Kopffeldern bis zur ersten Abschnittsüberschrift ist die Kurzbeschreibung, also die Zeile direkt unter dem Plugin-Namen; mehrere Zeilen oder Absätze fügt der Parser zu einer zusammen. Der Parser erlaubt 150 Zeichen, gezählt nach dem Entfernen von Markdown und HTML. Längerer Text wird an einem Punkt im letzten Fünftel der Grenze abgeschnitten, andernfalls mit Auslassungszeichen, und der Validator warnt. Fehlt die Zeile, springt die erste Zeile der Beschreibung ein.

Erwartet werden die Abschnitte Description, Installation, Frequently Asked Questions, Screenshots, Changelog und Upgrade Notice. Unbekannte Abschnitte gehen nicht verloren, sondern werden mit ihrem Titel als Zwischenüberschrift an die Beschreibung angehängt. Jeder Abschnitt ist auf 2500 Wörter begrenzt, FAQ und Changelog auf 5000; längerer Text wird gekürzt. FAQ-Einträge in der Form = Frage = werden auf der Plugin-Seite zu einer Definitionsliste, und die nummerierten Zeilen unter Screenshots werden zu den Bildunterschriften von screenshot-1, screenshot-2 und so weiter. Das Handbuch warnt, dass Readme-Dateien über 10 kB Fehler verursachen können, und empfiehlt, ältere Changelog-Einträge in eine eigene changelog.txt auszulagern.

Die Upgrade Notice ist kein Reiter auf der Plugin-Seite. Der Importer speichert sie getrennt, die Verzeichnis-API liefert sie aus, und WordPress zeigt sie als reinen Text unter Dashboard → Aktualisierungen neben dem anstehenden Update. Die offizielle Beispiel-Readme empfiehlt höchstens 300 Zeichen; der Parser setzt diese Grenze nicht durch.

Welcher Wert gewinnt, wenn Header und Readme sich widersprechen

Das Handbuch sagt nur allgemein, dass die Version aus der Hauptdatei kommt und der Rest aus der Readme. Der Import-Code des Verzeichnisses ist genauer. Die Tabelle fasst zusammen, was er mit Stand 29.09.2026 tut:

„Wohlgeformt“ heißt: mindestens drei Zeichen aus Ziffern und Punkten. Die Zeile zu „Tested up to“ wird leicht übersehen. Der Importer registriert Tested up to als zusätzliches Header-Feld der Hauptdatei, ein Wert dort überschreibt also die Readme, und Plugin Check meldet eine Abweichung zwischen beiden. Da der Core Anforderungen nur aus dem Header liest, sollten die Anforderungswerte in beiden Dateien identisch sein.

SVN-Aufbau: trunk, tags und assets

Nach der Freigabe bekommt jedes Plugin ein Repository unter https://plugins.svn.wordpress.org/<slug> mit drei Ordnern: trunk/ für den aktuellen Code, tags/ für Versionen und assets/ für Bilder und Blueprint. branches/ wird nicht mehr angelegt. Das Handbuch versteht SVN hier als Release-Repository: Jeder Commit baut die ZIP-Dateien aller Versionen neu, ein Grund dafür, dass Änderungen bis zu sechs Stunden brauchen können.

Wie der Stable tag den Code auswählt

Der Import beginnt bei trunk/readme.txt und liest daraus nur eine Zeile: Stable tag. Bei Stable tag: 1.2.0 sucht das Verzeichnis nach tags/1.2.0/. Existiert dieser Ordner und enthält er Dateien, kommt alles Weitere von dort: die angezeigte Readme, der Plugin-Header und die ZIP-Datei für die Nutzer. Änderungen an der Beschreibung in trunk/readme.txt wirken sich nicht aus, solange das Tag existiert. Auch die Readme im Tag muss den richtigen Stable tag tragen; sonst kann das Plugin laut Handbuch nicht mehr aktualisiert werden.

Der Ordnername wählt den Code aus, legt aber nicht die Version fest. Die Version auf dem Download-Button stammt aus dem Header Version der getaggten Hauptdatei. Steht in tags/1.4/ noch Version: 1.3, zeigt die Seite 1.3, und der Importer meldet, dass Header und Tag nicht zusammenpassen. Anführungszeichen um den Wert des Stable tag und ein Präfix tags/ entfernt der Parser.

Assets: Namen, Größen und der Blueprint

Alles in assets/ gilt für alle Versionen und gehört nicht zur ZIP-Datei. Bilder in trunk/assets/ oder tags/1.0/assets/ werden nicht verwendet. Die Dateinamen sind festgelegt:

Die Pixelmaße müssen zu den Namen passen, und das hochauflösende Banner funktioniert nur zusätzlich zum normalen. Dateinamen müssen kleingeschrieben sein. Banner und Screenshots lassen sich mit Suffixen wie -de lokalisieren, Banner auch mit -rtl. Wegen des CDN-Cachings können neue Bilder bis zu sechs Stunden brauchen.

Beim Blueprint akzeptiert der Importer nur gültiges JSON und hängt einen Schritt installPlugin mit Aktivierung an, wenn die Datei das Plugin nicht selbst installiert. Der Vorschau-Button ist nur für Committer sichtbar, bis ein Committer die Vorschau in der Advanced-Ansicht des Plugins öffentlich schaltet. Wie ein Blueprint entsteht, zeigt der Beitrag zu Playground und Blueprints in dieser Reihe.

Vollständige Befehlsfolge für die erste Version und ein Update

Der SVN-Benutzername ist der Benutzername auf WordPress.org, nicht die E-Mail-Adresse, und Groß- und Kleinschreibung zählt. Ein eigenes SVN-Passwort lässt sich im Profil auf WordPress.org festlegen. Die folgende Folge deckt die erste Veröffentlichung von Version 1.2.0 samt Assets ab:

# 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"

Zwischen den beiden Commits zeigt der Stable tag auf ein Tag, das noch nicht existiert; das Verzeichnis greift kurz auf trunk/ zurück, was das Handbuch als unbedenklich beschreibt. Die Zeile mit svn propset ist die dokumentierte Abhilfe, wenn Browser Bilder herunterladen statt sie anzuzeigen; für JPEG-Dateien lautet der Typ image/jpeg.

Für jede weitere Version empfiehlt das Handbuch, zuerst trunk/ einschließlich des neuen Stable tag zu bearbeiten, dann trunk mit svn cp in das neue Tag zu kopieren und beides in einem Schritt zu committen:

# 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"

Weil svn cp in der Arbeitskopie arbeitet, bleibt die Historie erhalten, und das Tag erhält genau die Dateien aus trunk/, einschließlich der Readme mit dem richtigen Stable tag. Alles, was committet wird, landet auf den Websites der Nutzer, auch eine .gitignore; ZIP-Archive gehören überhaupt nicht ins SVN.

Typische Fehler und der Readme-Validator

Die meisten Probleme nach einer Veröffentlichung gehen auf wenige Ursachen zurück:

• Stable tag zeigt auf ein nicht existierendes Tag. Der Importer fällt mit einer Warnung auf trunk/ zurück, und Nutzer bekommen, was gerade in trunk liegt, womöglich unfertigen Code.
• Stable tag: trunk. Das funktioniert noch, gilt laut Handbuch aber als nicht unterstützt und ist für neue Plugins verboten. Der Validator bemängelt jeden Stable tag, der „trunk“ enthält, und bei aktivierter Release-Bestätigung lehnt der Importer eine Veröffentlichung aus trunk ab.
• Tag angelegt, Header nicht angepasst. Die Seite zeigt weiter die alte Version, und der Importer meldet die Abweichung zwischen Version-Header und Tag.
• Readme nur in trunk geändert. Solange der Stable tag auf ein vorhandenes Tag zeigt, erscheint die Änderung nicht.
• Falsche Asset-Namen. Eigene Bannergrößen, großgeschriebene Dateinamen oder Assets in trunk/ werden ignoriert.
• Abhängigkeiten außerhalb des Verzeichnisses. Ein Slug in Requires Plugins, der kein veröffentlichtes Verzeichnis-Plugin ist, stoppt den Import.

Der Readme-Validator unter wordpress.org/plugins/developers/readme-validator/ nutzt denselben Parser wie das Verzeichnis. Er nimmt eingefügten Text an oder eine URL auf plugins.svn.wordpress.org, themes.svn.wordpress.org oder raw.githubusercontent.com bis 512 kB. Fehler sind etwa ein fehlender oder als Platzhalter stehen gelassener Name wie === Plugin Name ===, eine Marke im Namen und eine inkompatible Lizenz. Warnungen betreffen einen ungültigen Stable tag, ein fehlendes oder ignoriertes „Tested up to“, verworfene Contributors, überzählige Tags und gekürzten Text. Hinweise nennen fehlende optionale Teile wie FAQ, Changelog oder Screenshots. Der Validator sieht nur die Readme; ob das Tag existiert, die Version passt und Abhängigkeiten auflösbar sind, prüft erst der Import.

Grenzen und offene Punkte

Die Aussagen zur Rangfolge stützen sich auf den Quellcode des Verzeichnisses im GitHub-Spiegel des Meta-Repositorys mit Stand 29.09.2026. Dieser Code ändert sich häufig; allein die Import-Klasse erhielt im September 2026 mehrere Commits. Das Verhalten kann sich also ändern, ohne dass das Handbuch nachzieht.

Einige Punkte bleiben offen. Die Aussage im Handbuch, Readmes würden nicht mehr auf Anforderungen ausgewertet, bezieht sich auf den WordPress-Core; das Verzeichnis nutzt Readme-Werte weiterhin als Ersatz. Welchen Eintrag der Upgrade Notice die Update-API für ein bestimmtes Update auswählt, wurde nicht nachverfolgt. Wie streng die Suche nach Contributors mit Groß- und Kleinschreibung umgeht, wurde nicht getestet.

MIME-Typ-Befehle sind nur für PNG und JPEG dokumentiert, nicht für SVG-Icons. Die 10 kB für die Readme sind eher ein allgemeiner Hinweis als eine feste Grenze.

Das Beispiel-Plugin wurde nicht eingereicht. Auf einer Testinstallation mit WordPress 7.1.2 lässt es sich ohne Hinweise aktivieren, und Plugin Check 2.1.0 meldet dafür keine Fehler. Beide SVN-Befehlsfolgen liefen gegen ein lokales Repository fehlerfrei durch. Das beschriebene Verhalten des Validators stammt aus seinem Quellcode.