Updates und Kanäle

Plugin und Theme kommen nicht aus dem WordPress-Verzeichnis, sondern vom Update-Server updates.die-technikbude.de. Das gilt für jede Website. Das Child eines Vereins kommt nur dann von dort, wenn Die Technikbude den Verein selbst betreibt. Ein Child, das eine Agentur aus der Vorlage mit --no-updater gebaut hat, hat keinen Update-Hook und keinen Kanal, siehe Vorlage kopieren. WordPress bietet ein Update wie jedes andere an: unter Dashboard → Aktualisierungen und in der Liste der Plugins und Themes. Eine kleine Bibliothek, wp-dtb-updater, im Paket meldet es an.

Diese Seite erklärt, welche Versionen eine Website sieht, wie du auf einer Testwebsite Vorabversionen bekommst und wie ein Child auf eine neue Hauptversion umsteigt.

Ein Paket, ein Kanal je Hauptversion

Jedes Paket hat einen Ordner auf dem Server, in dem je Hauptversion (Major) ein Kanal liegt:

https://updates.die-technikbude.de/wp/<slug>/v1/info.json

Der Ordnername ist der Slug des Pakets: wp-club-elements für das Plugin, wpce-theme für das Theme und wpce-<kürzel> für ein Child. v1 steht für alle 1.x-Versionen, v0 für die 0.x-Versionen von früher. Eine Website fragt den Kanal ihrer eigenen Hauptversion. Sie sieht die nächste nicht: kein Hinweis, kein Knopf.

Stufe	Darf	Erreicht die Website
Fehlerbehebung und Nebenversion (1.0.1, 1.1)	hinzufügen und beheben. Nichts entfernen, nichts umbenennen	über den Kanal, als normales Update
Hauptversion (2.0)	brechen: Namen von Patterns, Template-Teilen, Token, Mindestversionen	nie von selbst

Eine Nebenversion zeigt WordPress wie jedes Plugin-Update an. Sie wird installiert, wenn ein Administrator klickt oder wenn er für dieses Paket die automatischen Aktualisierungen von WordPress eingeschaltet hat. Eine neue Hauptversion bietet der Kanal einer Website gar nicht erst an, darum kann auch die automatische Aktualisierung sie nicht einspielen.

Gepflegt werden die zwei neuesten Hauptversionen: Die aktuelle bekommt alles, die vorige noch Fehlerbehebungen. Ältere bekommen nichts mehr. Wann eine neue Hauptversion fällig ist, entscheidet der Bedarf, nicht der Kalender.

Drei Riegel gegen eine ungewollte Hauptversion

1. Der Kanal. Eine Website auf v1 fragt /v1/.
2. Die Bibliothek vergleicht. Antwortet der Server mit einer Version, deren Hauptversion nicht die erwartete ist, wird das Update verworfen. Das ist ein Sicherheitsnetz für den Fall, dass die Auslieferung einmal in den falschen Ordner schreibt.
3. Requires at least und Requires PHP im Paket. WordPress verweigert die Installation, wenn die Website die Mindestversionen nicht erfüllt, siehe Mindestversionen.

Von 0.x auf 1.0.0 umsteigen

Eine Website mit einer 0.x-Version des Plugins fragt den Kanal v0. Dort liegt keine 1.0.0, darum bietet WordPress ihr das Update nicht an. Das ist die Regel von oben: Eine Hauptversion kommt nie von selbst. Du holst die 1.0.0 einmal von Hand. Danach hat das Plugin die Hauptversion 1 im Kopf (Version:), die Website fragt v1, und die Updates innerhalb von 1.x kommen wieder von selbst.

1. Mach eine Sicherung der Datenbank.

2. Kommst du von 0.0.x? Dann führst du vorher einmal auf dem vorhandenen Inhalt aus: wp search-replace 'wp:wpce-plugin/' 'wp:wpce/'. Der Namensraum der Blöcke hat gewechselt, siehe Datenmigrationen. Von 0.1.0-rc.1 oder 0.1.0-rc.2 brauchst du das nicht.

3. Spiel die ZIP-Datei von Hand ein, über „Plugins“ → „Plugin hinzufügen“ → „Plugin hochladen“ (WordPress fragt, ob es die vorhandene Version ersetzen soll) oder mit WP-CLI:

   wp plugin install https://updates.die-technikbude.de/wp/wp-club-elements/v1/wp-club-elements-1.0.0.zip --force

4. Beim ersten Aufruf nach dem Austausch laufen die Datenmigrationen von selbst. wp wpce status zeigt, wo die Daten stehen.

Die Hauptversion lässt sich auch mit dem Filter dtb_updater_major/wp-club-elements oder mit der Konstante DTB_UPDATES_MAJOR umstellen, siehe unten. Ob die 0.x-Version, die auf deiner Website läuft, das schon kann, hängt von der Version der Update-Bibliothek in diesem Paket ab. Ich habe das nicht ausprobiert, der sichere Weg ist die ZIP-Datei.

Das beschreibt das Plugin. Für Theme und Child gilt dasselbe Prinzip, einen Kanal je Hauptversion; wie sie auf eine neue Hauptversion umsteigen, steht unten bei Ein Child auf eine neue Hauptversion heben.

Der Vorab-Kanal zum Testen

Neben jedem Kanal gibt es einen Vorab-Kanal:

…/wp/wp-club-elements/v1/info.json       nur fertige 1.x
…/wp/wp-club-elements/v1-rc/info.json    Vorabversionen und fertige 1.x

Ein Vorab-Tag wie v1.1.0-rc.1 schreibt nur in den Vorab-Kanal. Der fertige Tag v1.1.0 schreibt in beide. Darum bleibt eine Website, die den Vorab-Kanal liest, nicht auf der letzten Vorabversion hängen: Die Freigabe kommt als normales Update an, weil 1.4.0-rc.1 kleiner ist als 1.4.0. Die Schreibweise ist -rc.1, mit Punkt, nicht -rc1. Mit Punkt ordnet PHP rc.2 vor rc.10 richtig.

So schaltest du eine Website auf den Vorab-Kanal

Eine Testwebsite setzt in der wp-config.php eine Konstante:

define( 'DTB_UPDATES_CHANNEL', 'rc' );

Sie gilt für alle Pakete der Website. Einzeln für ein Paket geht es mit einem Filter, zum Beispiel in einem Mu-Plugin oder in der functions.php des Childs:

add_filter( 'dtb_updater_channel/wp-club-elements', fn() => 'rc' );

Der Filter schlägt die Konstante, die Konstante schlägt den Standard (der fertige Kanal). Eine Produktivwebsite setzt weder das eine noch das andere und sieht darum nie eine Vorabversion. Der einzige gültige Wert ist rc. Jeder andere wird abgelehnt und als fertiger Kanal behandelt. Ein Tippfehler in der wp-config.php schiebt eine Website also nicht auf einen Kanal, den es nicht gibt.

So wirken die Einstellungen:

Einstellung	Adresse der Metadaten
nichts	…/wp/wp-club-elements/v1/info.json
define( 'DTB_UPDATES_CHANNEL', 'rc' )	…/wp/wp-club-elements/v1-rc/info.json, auch für Theme und Child
Filter dtb_updater_channel/wp-club-elements gibt rc	…/wp-club-elements/v1-rc/…; Theme und Child bleiben auf v1
define( 'DTB_UPDATES_CHANNEL', 'beta' )	wie nichts: …/v1/info.json

Der Ablauf einer Veröffentlichung: entwickeln, -rc.1 taggen, auf einer Testwebsite mit dem Vorab-Kanal prüfen, bei Bedarf -rc.2, dann das fertige Tag setzen. Ein Major-Sprung wird genauso getestet: Testwebsite mit rc und dem Major-Filter.

Die Version im Kopf des Pakets (Version:) bleibt im Repository bei der Basis-Version (1.1.0). Nur die gebaute Kopie bekommt den Zusatz -rc.N. Genau der geprüfte Stand wird danach freigegeben.

Ein Child auf eine neue Hauptversion heben

Der Kanal ist eine Eigenschaft der Website, nicht des Parents. Ohne Angabe gilt die Hauptversion des installierten Pakets. Ein Child mit Update-Hook, gebaut für eine bestimmte Hauptversion, sagt, wenn es weiter ist. (Ein Child ohne Update-Hook, mit --no-updater aus der Vorlage gebaut, kann das nicht. Dort stellst du den Kanal des Themes mit der Konstante um, siehe unten.) Hast du es auf die nächste Hauptversion des Parents angepasst, setzt du in seiner functions.php:

add_filter( 'dtb_updater_major/wpce-theme', fn() => 2 );

Dieselbe Installation fragt ab jetzt /v2/, und WordPress bietet die 2.0 als normales Update an. Der Umstieg einer Website ist also: Child anpassen, Filter setzen, Child taggen. Eine Website ohne Child setzt denselben Filter in einem Mu-Plugin, wie beim Vorab-Kanal.

Mit dem Filter dtb_updater_major/wpce-theme auf 2 fragt nur das Theme den Kanal v2. Plugin und Child bleiben auf v1.

Der Theme-Ordner bleibt über alle Hauptversionen gleich. Im Kopf eines Childs ändert sich Template: wpce-theme nie.

Den Filter gibt es für jedes Paket unter dessen Slug (dtb_updater_major/<slug>). Für das Plugin heißt er dtb_updater_major/wp-club-elements.

Ohne Code geht dasselbe mit einer Konstante in der wp-config.php. Sie ist ein Array, ein Eintrag je Paket, nie eine einzelne Zahl, denn eine Website hat mehrere Pakete mit je einer eigenen Hauptversion:

define( 'DTB_UPDATES_MAJOR', array( 'wpce-theme' => 2 ) );

Der Filter schlägt die Konstante. Die Konstante kennt die Update-Bibliothek ab Version 1.1; das Plugin 1.0.0 liefert diese Version mit. Gegen den Quelltext der Bibliothek gelesen, nicht auf einer Website ausprobiert.

Was ein Update mit den Daten macht

Ein Plugin-Update ändert, wenn es sein muss, das Speicherformat von Inhalten. Das übernehmen Migrationen, siehe Datenmigrationen.

Was schiefgeht

• Das Child ohne Update-Hook. Ohne den Ordner vendor/ meldet sich das Child nicht beim Server. Es läuft, bekommt aber keine Updates. Bei einem Child, das mit --no-updater gebaut wurde, ist das gewollt: Plugin und Theme melden sich selbst.
• Der Vorab-Kanal auf einer Produktivwebsite. Sie bekäme Vorabversionen. Die Konstante gehört nur auf Testwebsites.
• Die 1.0.0 wird einer 0.x-Website nicht angeboten. Das ist so gewollt. Spiel die ZIP-Datei einmal von Hand ein, siehe Von 0.x auf 1.0.0 umsteigen.
• Eine Hauptversion erwartet, die nicht kommt. Sie kommt nie von selbst. Du setzt den Filter und gibst dem Child ein Tag.
• Ein Paket, das vor der Umstellung auf den Vorab-Kanal gebaut wurde. Es trägt keine -rc-Version in seinem Kopf und sieht nie eine Vorabversion. Installiere es einmal von Hand, dann klappt die Kette: wp theme install https://updates.die-technikbude.de/wp/<slug>/v<major>-rc/<slug>-<version>.zip --force (für ein Plugin wp plugin install …).