Der Vertrag (public-contract.json)

Ein Theme, das auf einem Plugin gebaut ist, bricht leise. Verschwindet ein Name, auf den es sich stützt, greift seine Regel einfach nicht mehr. Es gibt keine Fehlermeldung, die Seite sieht nur anders aus.

Darum steht fest, was du als Agentur oder Theme-Autor voraussetzen darfst. Das ist der Vertrag: eine Liste von Namen, die das Plugin nur mit einer neuen Hauptversion ändert.

Was im Vertrag steht

Die Liste liegt im Repository des Plugins unter docs/architecture/public-contract.json. Sie steht nicht im installierten Paket. Sie hat drei Teile:

• tokens: jede --wpce-*-Eigenschaft, die die Token-Schicht deklariert, und jede, die ein Block liest, ohne dass das Plugin sie setzt (ein Haken nur für Themes, etwa --wpce-pill-height). Eigenschaften, die ein Block für sich selbst setzt und wieder liest, gehören nicht dazu. Zurzeit sind es 71. Jedes steht mit Zweck auf der Seite Die Token –wpce-*.
• selectors: die Klasse, die WordPress jedem Block des Plugins gibt (.wp-block-wpce-<name>), und eine ausdrückliche Liste weiterer Klassen, auf die sich wpce-theme stützt. Zurzeit sind es 59: 30 Blöcke und 29 weitere Klassen, siehe unten.
• removed: was mit einer Hauptversion entfallen ist, mit der Version. Es ist zurzeit leer.

Die Blöcke, deren Klasse im Vertrag steht, sind genau die 30 Blöcke, die das Plugin registriert: die Vereinsdaten-Blöcke (club-name, club-logo, club-address, club-contact-details, club-bank-details, club-opening-hours), legal-notice, map, notice, timeline und timeline-item, collapsible und collapsible-summary, downloads, membership-fee-table, der Listen-Block entries, die Seitenblöcke entry-head und entry-facts und die zwölf Feld-Blöcke field-address, field-contact, field-files, field-gallery, field-image, field-opening-hours, field-place, field-relation, field-richtext, field-rooms, field-schedule, field-text.

Geprüft: Auf der Testwebsite mit dem Demoverein gibt es zu jeder Wrapper-Klasse im Vertrag einen registrierten Block wpce/* und zu jedem Block eine Klasse.

Die weiteren Klassen

Außer den Wrapper-Klassen sichert der Vertrag genau die Klassen zu, die wpce-theme für Layout und Bewegung braucht. Mehr nicht.

Wo	Klassen
Listen-Block	.wpce-entries (die Wurzel), .wpce-entries__item (ein Eintrag)
Listen-Block, je Darstellung	.wpce-entries--cards, .wpce-entries--list, .wpce-entries--table
Listen-Block, je Inhaltstyp	.wpce-entries--type-course, --type-event, --type-person, --type-section, --type-location, --type-label, --type-membership_fee, --type-downloads, --type-page
Blättern	.wpce-pagination, .wpce-pagination__link
Chronik	.wpce-timeline__item
Kontakte und Adresse	.wpce-contact, .wpce-contact--icon-only, .wpce-contact__item, .wpce-contact__value, .wpce-address, .wpce-icon
Öffnungszeiten	.wpce-opening-hours__day, .wpce-opening-hours__label
Logo	.wpce-club-logo, .wpce-club-logo__image
Hinweis	.wpce-notice
Seiten der Inhaltstypen	.wpce-page (am <main>)

Die Klasse --type-… eines Inhaltstyps, den ein Add-on anmeldet, gehört nicht zum Vertrag.

Worauf du dich verlassen darfst

• Jeden Token-Namen aus der Liste. Er verschwindet und ändert seine Bedeutung nur mit einer neuen Hauptversion.
• Die Wrapper-Klasse jedes Blocks, .wp-block-wpce-<name>, und die weiteren Klassen der Liste.
• Dass die Blöcke mit jedem Block-Theme ordentlich aussehen. Jedes Token fällt auf ein Preset des Themes und dann auf einen festen Wert zurück. Einige sind absichtlich leer und fallen dort zurück, wo sie gelten, siehe Die Token –wpce-*.

Nicht in der Datei, aber der vorgesehene Weg: die Blockstile des Listen-Blocks (siehe Block-Stile) und die Schlüssel unter settings.custom.wpce, die das Plugin liest. Mit ihnen stellt ein Theme die Blöcke ein. Anders als die Namen im Vertrag bewacht sie kein eigener Test. Schau vor jedem Major in die Änderungsliste.

Worauf du dich nicht verlassen darfst

• Das übrige innere Markup eines Blocks. Klassen wie .wpce-card oder .wpce-row__title, die nicht in der Liste stehen, sind kein Vertrag. Sie ändern sich in einer kleinen Version, ohne Hinweis. Ein Theme stellt Blöcke über Token und Blockstile ein, nicht über Selektoren in ihr Inneres.
• Die Reihenfolge und Verschachtelung der Elemente im Block.
• Eigenschaften, die nicht in der Liste stehen, auch wenn du sie im Quelltext siehst. Ein Block setzt für sich selbst Hilfsgrößen (zum Beispiel --wpce-card-fit). Die gehören ihm.
• Plugin-interne PHP-Klassen. Der Vertrag betrifft das Front-End. Für PHP gelten die Hooks, siehe Filter und Hooks.

Die Regeln des Vertrags

• Ein zugesagter Name verlässt den Vertrag nur mit einer Hauptversion (Major). Umbenennen ist Entfernen. Sechs interne Token hat das Plugin nach dem Release 1.0.0 ausdrücklich aus der Zusage genommen (Entscheidung vom 16. Oktober 2026); sie stehen auf der Seite Die Token –wpce-*.
• Eine Nebenversion und eine Fehlerbehebung fügen hinzu und beheben. Sie entfernen nichts und benennen nichts um.
• Wer einen Namen verschiebt, trägt ihn mit der Version in removed ein. Das ist Handarbeit, damit es niemand nebenbei tut.
• Eine Hauptversion erreicht eine Website nie von selbst, siehe Updates und Kanäle.

Der Test, der den Vertrag bewacht

Im Plugin prüft tests/js/public-contract.test.js (Jest, Teil von npm run check und der Pipeline):

1. Die Liste enthält Token und Selektoren.
2. Jedes Token der Liste gibt es noch in den Quellen (src/blocks/shared/_tokens.scss und den Block-Stylesheets). Fehlt eines, schlägt der Test fehl.
3. Jede Klasse der Liste gibt es noch: Zu jeder Wrapper-Klasse gibt es den Block, und jede weitere Klasse wird von einem Renderer des Plugins wirklich ausgegeben.
4. Bieten die Quellen einen neuen Namen an, der nicht in der Liste steht, schlägt der Test auch fehl.
5. Kein Name steht gleichzeitig im Vertrag und in removed.
6. Die Listen sind sortiert. Eine Änderung ist dadurch eine Zeile im Diff.

Neue Namen trägt npm run contract:update ein. Das Skript fügt nur hinzu. Aus den Quellen verschwundene Namen bleiben in der Datei, und der Test schlägt fehl, bis der Name wieder da ist oder von Hand nach removed wandert.

Die Gegenseite liegt im Theme. wpce-theme hält eine Kopie der Datei (tests/fixtures/plugin-public-contract.json) und prüft in plugin-contract.test.js gegen sie:

• Jede Klasse des Plugins, die das Theme irgendwo nennt – im Stylesheet, in PHP, in Skripten, in Vorlagen –, steht im Vertrag.
• Jede --wpce-*-Eigenschaft, die das Theme setzt, wird vom Theme oder vom Plugin gelesen oder steht im Vertrag.

Nach einem Release des Plugins wird die Kopie im Theme neu kopiert. Ein Child ist durch diesen Test nicht gedeckt. Wer in einem Child Klassen auswählt oder Token setzt, prüft sie selbst gegen die Liste.

Was das für dein Child heißt

• Setze Token aus der Liste, in der theme.json oder in assets/css/child.css. Das bleibt über Nebenversionen stabil.
• Wähle nur Klassen aus der Liste aus: die Wrapper-Klassen und die weiteren Klassen oben. Keine anderen Klassen im Inneren eines Blocks.
• Schau vor einem Major in die Datei. Taucht ein Name in removed auf, ist er in dieser Hauptversion weg. Das ist der Moment, dein Child anzupassen und dtb_updater_major/… zu setzen, siehe Vorlage kopieren.
• Eine Liste „Was ist überschrieben“ führen. Sie zeigt, wie viel vor dem nächsten Major zu tun ist.