Einfacher Weg um deine Extension auf TravisCI zu testen
Übersicht
- Einleitung
- Voraussetzungen
- Unterschiede zu Travis CI
- Was geprüft wird
- GitHub Actions einrichten
- Travis CI deaktivieren
- Anhang A: Repository Beispiele mit GitHub Actions
- Anhang B: Passend zum Thema
Bei phpBB wird für die CI Tests (Continuous Integration) nicht mehr Travis CI, sondern GitHub Actions eingesetzt. In diesem Thema wird erklärt, wie man ein GitHub Repository für die automatische Prüfung mittels GitHub Actions einrichten kann. Automatisch heisst, dass die Tests selbständig ausgeführt werden, sobald eine Änderung (neuer Commit) im Repository festgestellt wird. Man muss sich also nicht selber um die Ausführung der Tests kümmern, das geschieht automatisiert und transparent, also ohne die Arbeit mit dem Repository zu behindern.
2. Voraussetzungen
Wie die Bezeichnung "GitHub Actions" vermuten lässt, benötigt man einen GitHub Account sowie natürlich ein bereits vorhandenes Repository einer phpBB Erweiterung. In diesem Thema wird davon ausgegangen, dass bereits Grundkenntnisse in Bezug auf die Handhabung von GitHub und Repositorys vorhanden sind. Dieses Thema vermittelt nur zusätzliches Wissen, für allgemeine GitHub Tutorials müssen andere Quellen genutzt werden. Weiterhin wird in diesem Thema nur erklärt, wie die Standard Prüfungen eingerichtet werden. Für die erweiterten Prüfungen - die Unit Tests - mit denen eine Erweiterung tatsächlich unter verschiedenen PHP Versionen und mit verschiedenen MySQL Versionen getestet werden können, werden folgende (englischsprachige) Artikel und Themen empfohlen:
- [Info] Using GitHub Actions to Test Extensions - Darauf basiert dieses Thema.
- Unit Testing - Weiterführende Informationen zum Thema Unit Tests.
Vorab eine grobe Übersicht der Unterschiede von GitHub Actions und Travis CI für diejenigen, die bisher Travis genutzt haben. Diese Übersicht berücksichtigt nur die Standard Prüfungen, eventuelle Unterschiede bei den Unit Tests werden nicht aufgeführt.
- Bei Travis CI war die Einrichtung des Dienstes etwas umständlich, da mehrere Dateien benötigt wurden und hatte auch potentielle Stolpersteine, weil zum Beispiel einzelne Komponenten (Skripts) mittels CLI-Tool startfähig gemacht werden mussten, da dies über die GitHub Oberfläche nicht möglich war. Bei GitHub Actions ist die Einrichtung dagegen sehr einfach, weil nur eine einzige zusätzliche Datei benötigt wird und diese muss auch nicht speziell präpariert werden. Alles kann sehr einfach über die GitHub Oberfläche eingerichtet werden.
- Bei Travis CI gab es keine Übersicht der Prüfmodule und nur ein einziges Log ohne optische Trennung der einzelnen Log Abschnitte. Bei GitHub Actions gibt es dagegen eine Übersicht und separate Logs für jedes Prüfmodul.
- Bei Travis CI wurden die Tests von einer Dritt-Seite (travis-ci.org) ausgeführt und die Berichte auch dort gespeichert. Dazu wurde der GitHub Account mit dem Travis Dienst gekoppelt. Bei GitHub Actions werden die Tests von GitHub selbst ausgeführt und die Berichte werden auch von GitHub verwaltet.
- Das kostenfreie Travis CI erlaubte keine Prüfung von Repositorys die als privat deklariert sind, zum Beispiel Repositorys die nur zum testen verwendet werden. Bei GitHub Actions ist die Prüfung von privaten Repositorys dagegen erlaubt.
4. Was geprüft wird
Die folgenden Tests/Prüfungen werden ausgeführt:
- Extension Pre Validator (Name in Konfigurationsdatei:
EPV)
Analysetool zur Überprüfung der Spezifikationen für Erweiterungen nach phpBB-Standard.
Die wohl wichtigste Prüfung. Hier werden spezifische phpBB Merkmale einer Erweiterung geprüft. Unter anderem werden Vorgaben in dercomposer.jsongeprüft und viele weitere Details wie zum Beispiel ob alle Sprachpakete exakt das gleiche Set Sprachvariablen enthalten. Der Prüfumfang von EPV ist komplex und deshalb ist EPV ein hilfreiches Werkzeug um Fehler bei den Strukturen einer Erweiterung aufzudecken.
- phpBB PHP Strict Standard Extensions (Name in Konfigurationsdatei:
SNIFF)
Ein Regelwerk für CodeSniffer zur Überprüfung der Programmierrichtlinien nach phpBB-Standard.
In der Konfigurationsdatei wird dieser Test mit SNIFF bezeichnet und bezieht sich damit auf das Tool, welches dabei ausgeführt wird: PHPCodeSniffer. Im phpBB Umfeld wird PSSE (PHP Strict Standard Extensions) also auch oft synonym mit "CodeSniffer" oder kurz "Sniffer" bezeichnet. Bei diesem Test werden umfangreiche Vorgaben bezüglich dem Programmcode geprüft. Durch diesen Test soll also sichergestellt werden, dass die Erweiterung ein Mindestmass an Code-Qualität aufweist und den offiziellen phpBB Programmierrichtlinien entspricht. Zum Beispiel sind Inline-Control-Strukturen prinzipiell nicht erlaubt und werden direkt als Fehler gemeldet.
- Image ICC Profile (Name in Konfigurationsdatei:
IMAGE_ICC)
Prüft Bilddateien auf eingebettete Copyright-Daten, die mit der GNU Lizenz von phpBB nicht vereinbar sind.
Wer grundsätzlich keine Bilddateien in seiner Erweiterung hat, könnte diesen Test theoretisch auch deaktivieren.
- Executable Files (Name in Konfigurationsdatei:
EXECUTABLE_FILES)
Prüft ob bei Dateien im Repository das eXecutable Flag gesetzt ist, was nicht erlaubt ist.
Dieser Test dient der Sicherheit um unerwünschte (potentiell schädliche) Aktionen seitens der Erweiterung auszuschliessen.
Die nachfolgenden Schritte gelten für die Web-Oberfläche von GitHub. Wer mit lokalen Repositorys arbeitet und direkt Git nutzt, oder einen Git-GUI-Client wie z.B. GitHub Desktop, SmartGit, Sourcetree, GitKraken usw., kann natürlich das nutzen um die Datei hinzuzufügen.
1. Im Wurzelverzeichnis des GitHub Repositorys auf "Add file" klicken und "Create new file" auswählen.
2. Im Textfeld
.github/workflows/tests.yml einfügen. Dabei wird auch automatisch die benötigte Ordnerstruktur erzeugt.3. Im Editor den folgenden Inhalt einfügen:
Code: Alles auswählen
name: Tests
env:
EXTNAME: vendor/ext # Your extension vendor/package name
SNIFF: 1 # Run code sniffer on your code? 1 or 0
IMAGE_ICC: 1 # Run icc profile sniffer on your images? 1 or 0
EPV: 1 # Run EPV (Extension Pre Validator) on your code? 1 or 0
EXECUTABLE_FILES: 1 # Run check for executable files? 1 or 0
PHPBB_BRANCH: 3.3.x # The phpBB branch to run tests on
on:
push:
branches: # Run tests when commits are pushed to these branches in your repo
- master
- develop
pull_request: # Run tests when pull requests are made on these branches in your repo
branches:
- master
- develop
jobs:
# START Basic Checks Job (EPV, code sniffer, images check, etc.)
basic-checks:
runs-on: ubuntu-20.04
strategy:
matrix:
include:
- php: '7.3'
db: "none"
NOTESTS: 1
name: PHP ${{ matrix.php }} - ${{ matrix.db }}
steps:
- name: Checkout phpBB
uses: actions/checkout@v2
with:
repository: phpbb/phpbb
ref: ${{ env.PHPBB_BRANCH }}
path: phpBB3
- name: Checkout extension
uses: actions/checkout@v2
with:
path: phpBB3/phpBB/ext/${{ env.EXTNAME }}
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: ${{ matrix.php }}
extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, mysqli, sqlite, pdo_sqlite, intl, gd, exif, iconv, sqlsrv, pdo_sqlsrv, ldap
coverage: none
- name: Setup environment for phpBB
env:
DB: ${{ matrix.db }}
PHP_VERSION: ${{ matrix.php }}
NOTESTS: '1'
run: .github/setup-phpbb.sh $DB $PHP_VERSION $NOTESTS
working-directory: ./phpBB3
- name: Setup EPV
if: ${{ env.EPV != 0 }}
run: composer require phpbb/epv:dev-master --dev --no-interaction --ignore-platform-reqs
working-directory: ./phpBB3/phpBB
- name: Run code sniffer
if: ${{ env.SNIFF != 0 }}
env:
NOTESTS: '1'
run: .github/ext-sniff.sh $EXTNAME $NOTESTS
working-directory: ./phpBB3
- name: Check image ICC profiles
if: ${{ env.IMAGE_ICC != 0 }}
run: .github/check-image-icc-profiles.sh
working-directory: ./phpBB3
- name: Check executable files
if: ${{ env.EXECUTABLE_FILES != 0 }}
run: .github/ext-check-executable-files.sh ./ $EXTNAME
working-directory: ./phpBB3
- name: Run EPV
if: ${{ env.EPV != 0 }}
run: phpBB/vendor/bin/EPV.php run --dir="phpBB/ext/$EXTNAME/"
working-directory: ./phpBB3
# END Basic Checks Job
Hinweis: Die hier gezeigte Konfigurationsdatei ist nicht geeignet für Unit Tests, da sie für die Standard Prüfungen auf das Wesentliche reduziert wurde.
4. Im Editor muss diese Datei dann noch an die eigene Erweiterung angepasst werden, indem vendor/ext mit dem korrekten Wert ersetzt wird. Dazu wird der Wert benötigt der in der eigenen Erweiterung in composer.json bei "name": eingetragen wurde. Am Beispiel von "LF who was here 2" wäre das lukewcs/whowashere, also müsste in meinem Fall der Anfang der Datei schlussendlich so aussehen:Code: Alles auswählen
name: Tests
env:
EXTNAME: lukewcs/whowashere # Your extension vendor/package name
SNIFF: 1 # Run code sniffer on your code? 1 or 0
IMAGE_ICC: 1 # Run icc profile sniffer on your images? 1 or 0
EPV: 1 # Run EPV (Extension Pre Validator) on your code? 1 or 0
EXECUTABLE_FILES: 1 # Run check for executable files? 1 or 0
PHPBB_BRANCH: 3.3.x # The phpBB branch to run tests on
...
6. Jetzt sollte man im Wurzelverzeichnis des Repositorys einen orangen Punkt vor der Commit-ID bemerken. Wenn dieser Punkt zu sehen ist, war die Einrichtung von GitHub Actions erfolgreich. Eventuell muss man das Wurzelverzeichnis kurz neu laden damit der Punkt sichtbar wird. Wenn man auf diesen orangen Punkt klickt, kann man in Echtzeit die Prüfungen verfolgen.
Tipp: Wenn man in der Navigationsleiste des Repositorys auf "Actions" klickt, kann man sich eine Übersicht aller bisherigen Prüfungen anzeigen lassen und kann dort auch jederzeit sämtliche Berichte erneut sichten.
7. In der Datei README.md (im Wurzelverzeichnis) an beliebiger Stelle folgenden Markdown Code einfügen:Code: Alles auswählen
[](https://github.com/GITHUB-USERNAME/REPO-NAME/actions)GITHUB-USERNAME/REPO-NAME (kommt zweimal vor) durch die eigenen Angaben ersetzt werden. Um beim Beispiel "LF who was here 2" zu bleiben wäre das LukeWCS/lf-who-was-here-2, dieser Teil wird von der URL zum Repo abgeleitet: https://github.com/LukeWCS/lf-who-was-here-2. Der Markdown Code müsste in meinem Fall also schlussendlich so aussehen:Code: Alles auswählen
[](https://github.com/LukeWCS/lf-who-was-here-2/actions)8. Den neuen Ordner
.github in der Datei .gitattributes (im Wurzelverzeichnis) vom Export ausschliessen. Dieser Ordner ist für Benutzer irrelevant und sollte nicht im Download-Archiv der Erweiterung enthalten sein.Code: Alles auswählen
.github/ export-ignoreDie nachfolgenden Tätigkeiten sind nur relevant, wenn das Repository bisher für Travis CI eingerichtet war. Wenn das nicht der Fall ist, kann dieser Punkt komplett ignoriert werden.
- Den Ordner
travisund die Datei.travis.ymllöschen. Dadurch wird Travis effektiv für dieses Repository deaktiviert. - Sofern bisher eine Travis CI Plakette in der Readme eingefügt war, muss deren Markdown Code natürlich aus der
README.mdentfernt werden.
Anhang B: Passend zum Thema
- Eine Alternative zu GitHub Actions wäre phpBB Ext Check, zumindest was die Standard Prüfungen angeht. Damit kann eine Erweiterung ebenfalls mittels "Extension Pre Validator" und "phpBB PHP Strict Standard Extensions" getestet werden, bietet darüberhinaus aber noch weitere Prüfungen an. phpBB Ext Check steht jedem Entwickler zur Verfügung der ein Benutzerkonto bei phpbb.de oder phpbb.com hat und nachweislich an einer Erweiterung arbeitet oder schon veröffentlicht hat.
