Veröffentlichung im TYPO3 Extension Repository [TER] am Beispiel von t2_scss

Möchte man eine Extension im TYPO3 Extension Repository, kurz TER, veröffentlichen und der Community etwas zurückgeben, so sollte man einiges an Zeit mitbringen. Denn bei einer Veröffentlichung gibt es einiges zu beachten. Was das genau ist, das haben wir hier an dem Beispiel unserer eigenen Extension t2_scss einmal zusammengefasst.

Name

Zunächst mussten wir uns Gedanken über den Namen der Extension machen. Kurz und beschreibend sollte er sein, zudem unser Kürzel enthalten. Da unsere Extension Scss verarbeiten sollte, haben wir uns für den Namen t2_scss entschieden.

Lizenz

Das TYPO3 CMS ist ein Open Source-Projekt. Der Code unterliegt der General Public License von GNU, das heißt, dass der Quellcode für beliebige Zwecke verwendet werden darf, sofern die Lizenz beibehalten wird. Es empfiehlt sich daher, bei der Veröffentlichung einer Extension auf die gleiche Lizenz zurückzugreifen. Dieser Empfehlung sind wir gefolgt und haben uns ebenfalls für die GNU GPL in der Version 3 entschieden. Zur Wahl standen zudem MIT, Apache 2.0 und BSD.

Sauberer Quellcode

Bevor man mit dem Quellcode seiner Extension überhaupt an die Öffentlichkeit geht, sollte dieser sauber und getestet sein. Am besten hält man sich dabei an die Coding-Standards von TYPO3 oder aber die allgemeinen PHP Standards Recommendations, kurz PSR. Da unsere internen Standards weitestgehend mit PSR übereinstimmen, gab es damit keine großen Probleme. Allerdings haben wir zuvor den Aufbau des Codes optimiert, sodass einige Fragmente entfallen konnten und der Code insgesamt schlanker und verständlicher geworden ist.

Composer

Composer ist ein Tool zur Verwaltung von Abhängigkeiten bei PHP-Anwendungen. Das Tool installiert extern benötigte Librarys und prüft unter anderem, ob die Plattform in der benötigten Version vorliegt. So lässt sich zum Beispiel das TYPO3 CMS wesentlich leichter installieren als mit der herkömmlichen, manuellen Weise. Außerdem ist es so deutlich einfacher Extensions oder andere Librarys in die TYPO3-Installation aufzunehmen. Für das TER ist Composer zwar nicht nötig, allerdings gehen wir derzeit davon aus, dass die aktuelle Form des TER in einigen Jahren vollständig durch eine Composer-Lösung ersetzt wird. TYPO3 selbst empfiehlt bereits die Verwendung von Composer, sodass viele Installationen mittlerweile ausschließlich Extensions über Composer beziehen. Wer seine Extension also allen zur Verfügung stellen möchte, kommt an Composer nicht vorbei.

Für unsere Extension war Composer auch deshalb von Bedeutung, da wir eine externe Library verwenden. In unserer Composer-Konfiguration haben wir daher noch eine zusätzliche Abhängigkeit angegeben, die automatisch bei der Installation über Composer mit geladen wird. Für die spätere Veröffentlichung im TER wurde das zu einer kleinen Herausforderung, dazu aber später mehr.

Qualitätssicherung

Bevor man mit der Qualitätssicherung starten kann, sollte man die Plattformanforderungen definieren, also unter welchen PHP- und TYPO3-Versionen die Extension überhaupt laufen können soll. In unserem Fall haben wir die Extension für PHP 7.1 bis 7.4 und TYPO3 7.6 bis 10.5 gekennzeichnet. Die Qualitätssicherung erfolgte im Anschluss unter allen Plattformen und auch mit unterschiedlichen Kombinationen.

Dokumentation

Wer eine Extension schreibt, ist mit deren Funktionalität vermutlich bestens vertraut, die zukünftigen Nutzer der Extension dagegen nicht. Deshalb ist es unabdingbar, dass man die Extension so dokumentiert, dass auch ein unerfahrener Entwickler weiß, wie die Extension zu verwenden und zu konfigurieren ist. Dass die Dokumentation in englischer Sprache verfasst sein sollte, ist selbstverständlich.

Im TYPO3-Kosmos wird für Dokumentationen das Format RST (reStructuredText) verwendet. Das ist ein standardisiertes Textformat, das sich später in besser lesbares HTML konvertieren lässt. So ist beispielsweise die gesamte TYPO3-Dokumentation in diesem Format geschrieben worden und auch externe Extensions können so in die offizielle Doku mit eingebunden werden. Aus diesem Grund kommt auch bei der t2_scss eine Dokumentation im RST-Format zum Einsatz. Das Format ist unserer Meinung nach zwar ein wenig sperriger als zum Beispiel Markdown, aber eben das Mittel der Wahl.

Es ist im Übrigen auch möglich im TER eine externe Dokumentation für seine Extension anzugeben, wenn die Strukturierung etwas komplexer ist oder man mit dem RST-Format nicht zurechtkommt. Unserer Ansicht nach ist es aber schöner, wenn die Dokumentation der Extension auch in der offiziellen Doku wiederzufinden ist.

Git-Repository

Ein öffentliches Git-Repository, über das der versionierte Quellcode eingesehen werden kann, ist zwar nicht zwingend notwendig für die Veröffentlichung im TER, aber absolut zu empfehlen. Warum das zu empfehlen ist, dazu später mehr.

Am häufigsten kommt dabei GitHub zum Einsatz, einem Anbieter von kostenlosen, öffentlichen Git-Repositorys. Aber es gibt auch weitere Alternativen wie GitLab, Bitbucket oder ein selbst gehostetes Repository.

Wir haben uns für den bekanntesten Anbieter GitHub entschieden, auch weil wir dort Issues von Nutzern der Extension erfassen können. Allerdings verwenden wir das öffentliche GitHub-Repository nur als Spiegel für unser intern gehostetes Repository. Ein Job in unserem Continuous Deployment Tool kümmert sich dabei um die Synchronisation zwischen GitHub und unserem internen Git-Server.

Packagist

Packagist ist der Paketmanager von PHP und eng verknüpft mit Composer. Pakete (also Librarys oder auch TYPO3 Extensions) die über Composer installiert werden, kommen primär aus Packagist. Um den Composer-Nutzern eine TYPO3 Extension anbieten zu können, muss die Extension als Paket vorliegen. Dazu reicht es, beim Anlegen des Pakets auf Packagist ein GitHub-Repository mit einer gültigen Composer-Konfiguration anzugeben. Anschließend legt man in GitHub noch einen Webhook an, der Packagist bei Änderungen benachrichtigt, sodass bei einem Release das neue Paket automatisch angelegt wird. Ein Release entspricht einem Git-Tag mit einer semantischen Versionsnummer.

TYPO3 Extension Repository

Im Grunde ist die Extension bereits veröffentlicht und kann – mittels Composer – von jedem installiert und genutzt werden. Nur dürfte sie noch Niemandem bekannt sein und vermutlich auch nur schwer gefunden werden. Um das zu ändern, veröffentlicht man die Extension zusätzlich noch im TER. Die Extension ist dann gelistet und kann auch über das TYPO3 Backend installiert werden. Dazu ist ein Account auf typo3.org notwendig, mit dem ein neuer Extension-Key angelegt werden kann. Über das Interface lässt sich die Extension auch als ZIP-Archiv hochladen und damit in einem Release veröffentlichen.

Da schlaue Entwickler gerne automatisieren (und da zählen wir uns einmal dazu), stellt TYPO3 auch eine SOAP-Schnittstelle zur Verfügung, über die sich ein neuer Release abbilden lässt. Ein Community-Mitglied war so freundlich und hat dafür extra einen Client bereitgestellt. So konnten wir in unserem Continuous Deployment Tool einen Job anlegen, der bei einem neuen Tag im Git-Repository automatisch einen Upload über den TER-Client ausführt und uns damit ein manueller Schritt über das Interface erspart bleibt.

Wie weiter oben bereits angekündigt hatten wir an dieser Stelle noch eine kleine Herausforderung zu meistern, denn unsere externe Library, die über Composer angegeben ist, wird bei der Installation über das TER nicht automatisch mit geladen. Deshalb haben wir im Extension-Code eine Weiche eingebaut, die dafür sorgt, dass die Library aus einem festgelegten Verzeichnis innerhalb der Extension geladen wird. Dieses Verzeichnis wird nur bei der TER-Version gefüllt und bleibt bei der Composer-Version einfach leer. Unser Release-Job kümmert sich darum, dass die Library (über Composer) geladen und mit in den TER-Release aufgenommen wird.

Dokumentation

Im letzten Schritt geht es ein weiteres Mal um die Dokumentation. Wie weiter oben beschrieben, soll die Extension auch in der offiziellen Doku auftauchen. Damit das zukünftig auch automatisch passiert, müssen ein paar Voraussetzungen gegeben sein.

Zunächst einmal muss im Extension-Verzeichnis ein Ordner Documentation vorliegen, in dem die Dokumentation im RST-Format gespeichert ist. Außerdem ist eine Composer-Konfiguration Pflicht, da dort einige Informationen für das Rendering abgerufen werden. Dann wird noch ein Webhook benötigt, der die TYPO3-Website darüber informiert, dass bei einem Release eine aktualisierte Version der Dokumentation zum Rendering vorliegt. Am einfachsten lässt sich der Webhook über GitHub einrichten.

Bei der ersten Einreichung wird die Dokumentation übrigens noch überprüft. Bei den nachfolgenden Aktualisierungen passiert das dann aber vollständig automatisiert.

Abschluss

Wie man sieht, sollte man sich für eine Veröffentlichung einer Extension im TER etwas Zeit nehmen. Zumindest wenn man der Community wirklich etwas zurückgeben möchte. Einige der beschriebenen Schritte können theoretisch auch weggelassen werden, aber am Ende ist mit einer undokumentierten und unsauberen Extension ohne Composer-Unterstützung auch niemandem geholfen. Wir haben uns die Zeit genommen und hoffen, dass die TYPO3 Community dadurch gestärkt wurde. Verdient hat sie es in jedem Fall!


Ihre Ansprechpartner

Foto Michael Schiller
Michael Schiller

Geschäftsführender Gesellschafter

0201 - 878 499 11 E-Mail senden
Foto Daniel Jarusch
Daniel Jarusch

Geschäftsführender Gesellschafter

0201 - 878 499 12 E-Mail senden