WordPress-Contributor werden: Der Weg zum ersten Patch

In diesem Beitrag zeige ich euch, wie ihr einen Patch für den WordPress-Core erstellen könnt – inklusive der notwendigen Vorbereitungen.

Ich nutze WordPress nun schon seit ein paar Jahren und habe mich bereits mit Theme- und auch ein bisschen mit Plugin-Entwicklung auseinandergesetzt. Was ich bisher noch nicht angegangen bin, ist das Beitragen (contributing) zum Core von WordPress, also der Software selbst. In diesem Artikel werde ich euch den Weg zum ersten Core-Patch inklusive notwendiger Vorbereitungen vorstellen.

Vorausgesetzt wird in diesem Tutorial, dass ihr bereits einen lokalen Webserver wie XAMPP für Windows oder MAMP für Mac eingerichtet habt. Da ich selbst mit Windows arbeite, habe ich diesen Weg auch mit einem Windows-PC beschritten und beschreibe deshalb eventuell Dinge, die für einen Mac- oder Linux-Nutzer nicht notwendig sind.

Vorbereitungen

Um einen Patch für WordPress zu schreiben oder zu testen, wird zunächst die Trunk-Version, also die aktuelle Entwicklerversion, benötigt. Die findet ihr im SVN-Repo und könnt ihr über den folgenden Befehl in ein Verzeichnis wordpress-trunk auf eurem PC holen (am besten natürlich im htdocs-Verzeichnis eures lokalen Webservers):

svn co https://develop.svn.wordpress.org/trunk wordpress-trunk

Damit ihr den SVN-Befehl ausführen könnt, müsst ihr zuerst SVN installieren. Dabei gibt es OS-abhängig unterschiedliche Wege:

Für Windows-Nutzer: Ihr könnt euch einfach TortoiseSVN herunterladen und installieren – anschließend ist svn in der Kommandozeile ausführbar.
Für Mac-Nutzer: Auf der offiziellen SVN-Website gibt es verschiedene Wege, wie ihr es installieren könnt – im Core-Handbuch wird Cornerstone empfohlen.
Für Linux-Nutzer: Ebenfalls auf der SVN-Website gibt es Anleitungen für die verschiedenen Linux-Distributionen, wie SVN installiert werden kann.

Nachdem der Befehl erfolgreich ausgeführt wurde, findet ihr in dem Ordner wordpress-trunk unter anderem einen src-Ordner. Hier befindet sich die „Rohversion“ von WordPress – hier liegen die CSS-Dateien beispielsweise nur in unminimierter Version vor. Beim Build-Prozess wird jeweils noch eine minimierte Version erstellt.

Neben dem src-Verzeichnis gibt es noch tests und tools, mit denen wir uns hier aber nicht näher befassen werden. Auf der obersten Ordner-Ebene liegen Dateien wie beispielsweise eine Gruntfile.js und eine package.json.

Um aus der Rohversion des Cores einen Build zu erstellen, mit dem ihr eure Anpassungen testen könnt, muss Grunt installiert werden, das nodeJS und npm voraussetzt. npm kommt mit nodeJS daher, muss also nicht extra installiert werden. Um nodeJS zu installieren, findet ihr auf der Download-Seite von nodeJS Installer für Windows und Mac sowie Binaries für Linux.

Nach der Installation könnt ihr global das CLI von Grunt installieren, indem ihr folgenden Befehl in der Kommandozeile ausführt, die ihr auf Windows dafür als Administrator ausführen müsst:

npm install -g grunt-cli

Nun müsst ihr in der Kommandozeile in das wordpress-trunk-Verzeichnis wechseln, und folgende Befehle ausführen:

npm install
grunt

Ihr solltet jetzt zwei neue Ordner sehen: Einmal den Ordner build und einmal den Ordner node_modules. Unter build findet ihr immer die WordPress-Dateien, die ihr testet. Um die wp-config.php nicht nach jedem Build-Prozess neu erstellen zu müssen, können wir sie im übergeordneten Verzeichnis ablegen, also direkt in wordpress-trunk. Nehmt dafür einfach die wp-config-sample.php, die bereits im wordpress-trunk liegt, benennt sie um und passt die Datenbankinformationen an. Damit ihr auch die Unit Tests ausführen könnt, kopiert gleich auch die wp-tests-config-sample.php und nennt sie wp-tests-config.php. Hier müsst ihr eine separate Datenbank nutzen, da die Datenbank vor Durchführung der Unit Tests immer geleert wird.

Und wo wir gerade bei Unit Tests sind: Damit die ausgeführt werden können, muss erst mal PHPUnit installiert werden. Voraussetzung für PHPUnit ist PHP, das bei eurem lokalen Webserver schon dabei sein sollte.

Für Windows-Nutzer: Um PHP auf Windows global zugänglich zu machen, erstellen wir eine weitere Umgebungsvariable, die bei mir auf folgenden Pfad zeigt:

C:\xampp\php

Um PHPUnit zu installieren, könnt ihr einfach der Anleitung für euer jeweiliges Betriebssystem folgen.

Jetzt könnt ihr ganz normal den Pfad des build-Verzeichnisses aufrufen und die WordPress-Installation ausführen. Danach seid ihr bereit, Änderungen vorzunehmen und zu testen. Dabei geht ihr immer wie folgt vor:

  1. Bringt euren Trunk auf den aktuellsten Stand, indem ihr im wordpress-trunk-Verzeichnis svn up ausführt
  2. Führt im selben Verzeichnis phpunit aus, um die Unit Tests durchzuführen
  3. Nehmt die Änderungen für den Patch im src-Verzeichnis vor
  4. Führt im wordpress-trunk-Verzeichnis den Befehl grunt aus, um den Build zu aktualisieren
  5. Testet die Änderungen in der Installation im build-Verzeichnis
  6. Führt erneut die Unit Tests aus, damit ihr sicher sein könnt, nichts verschlimmert zu haben

Patch erstellen

Wenn alles zu eurer Zufriedenheit ist, und eure Anpassungen ein Problem aus einem Ticket beheben, dann wird es Zeit, einen Patch zu erstellen. Bevor ihr das macht, führt zur Sicherheit im wordpress-trunk-Verzeichnis den Befehl svn diff aus, um sicherzustellen, dass keine Änderungen am Code vorgenommen wurden, die nicht in euren Patch gehören. Wenn eine Änderung aufgeführt werden sollte, die nicht beabsichtigt ist, dann könnt ihr mit folgendem Befehl beispielsweise die Änderungen in der forms.css rückgängig machen:

svn revert src/wp-admin/css/forms.css

Um einen Patch auf Basis der Veränderungen am Code zu erstellen, müsst ihr lediglich folgenden Befehl ausführen, wobei die Nummer mit der Ticket-Nummer übereinstimmen sollte, zu der ihr den Patch hochladen wollt:

svn diff > 12345.patch

Danach findet ihr im wordpress-trunk-Verzeichnis eine Patch-Datei, die ihr zu dem Ticket hochladen könnt – dafür nutzt ihr den „Attach file“-Button in dem „Attachments“-Bereich des Tickets. Anschließend bringt ihr euren Trunk wieder auf den Ursprungszustand, indem ihr mit svn revert die Patch-Änderungen rückgängig macht.

Schnelldurchlauf:

  1. Trunk mit svn up auf aktuellsten Stand bringen
  2. Mit svn diff auf unabsichtliche Änderungen testen und gegebenenfalls mit svn revert rückgängig machen, solange bis svn diff kein Ergebnis liefert
  3. phpunit ausführen, um Unit Tests durchzuführen
  4. Änderungen im src-Verzeichnis vornehmen
  5. In wordpress-trunk den Befehl grunt ausführen, um Build zu erzeugen
  6. Änderungen in der build-Installation testen
  7. Falls ihr könnt, Unit Tests für die Änderung erstellen
  8. Unit Tests erneut ausführen, um zu prüfen, ob alles noch so ist wie vorher
  9. Mit svn diff > 12345.patch einen Patch erstellen
  10. Patch hochladen
  11. Trunk mit svn revert wieder auf Ursprungszustand zurücksetzen

Einen Patch testen

Um einen Patch von jemand anderem zu testen, könnt ihr auf Mac OSX und Linux einfach die folgende Zeile im wordpress-trunk-Verzeichnis ausführen, nachdem ihr es per svn revert wieder auf denselben Stand wie den Trunk gebracht habt:

grunt patch:35596

Falls mehrere Patches zu dem Ticket hochgeladen wurden, bekommt ihr nach dem Befehl eine Liste angezeigt, aus der ihr mit den Pfeiltasten den richtigen Patch auswählen könnt.

Für meine Windows-Umgebung habe ich auf die Schnelle keine zufriedenstellende Lösung gefunden, wie das patch-Statement in der Kommandozeile genutzt werden kann. Hier muss ich den Patch aus dem Trunk herunterladen, in das wordpress-trunk-Verzeichnis verschieben und über einen Rechtsklick auf die .patch-Datei die Option „TortoiseSVN“ › „Apply Patch“ wählen.

Anschließend testet ihr die Änderungen genau so, wie wenn ihr selbst eine Veränderung vorgenommen hättet.

Unit Tests

Ich selbst habe für meinen ersten Patch lediglich einen Hex-Code in einer CSS-Datei verändert, wofür kein Unit Test notwendig ist – dementsprechend wenig kenne ich mich selbst mit der Erstellung eines Unit Tests aus. Sal Ferrarello hat auf seiner Website seine Erfahrungen beim Erstellen eines Unit Tests aufgeschrieben, und das Core-Team von WordPress möchte in naher Zukunft den Prozess an offizieller Stelle dokumentieren.

Veröffentlicht in Core

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.