Eine Erweiterung automatisch mit GitHub Actions testen

In diesem Forum gibt es Starthilfe zum neuen Extension-System von phpBB 3.1/3.2. Fragen zur Entwicklung von Extensions und zur Konvertierung von phpBB 3.0.x MODs sind ebenfalls willkommen.
Antworten
Benutzeravatar
LukeWCS
Supporter
Supporter
Beiträge: 2091
Registriert: 15.12.2014 10:19
Kontaktdaten:

Eine Erweiterung automatisch mit GitHub Actions testen

Beitrag von LukeWCS »

Dieses Thema ist - zumindest teilweise - als Nachfolger für das Travis CI Thema von nickvergessen konzipiert:
Einfacher Weg um deine Extension auf TravisCI zu testen

Übersicht
  1. Einleitung
  2. Voraussetzungen
  3. Unterschiede zu Travis CI
  4. Was geprüft wird
  5. GitHub Actions einrichten
  6. Travis CI deaktivieren
  • Anhang A: Repository Beispiele mit GitHub Actions
  • Anhang B: Passend zum Thema
1. Einleitung

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:
3. Unterschiede zu Travis CI

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.
Das sind in Bezug auf die Standard Prüfungen die wohl interessantesten Unterschiede. GitHub Actions stellt also in Bezug auf die Einrichtung und Handhabung eine deutliche Verbesserung dar und ist somit auch für weniger versierte Entwickler geeignet.

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 der composer.json geprü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.
5. GitHub Actions einrichten

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

...
5. Abschliessend "Commit new file" klicken, wodurch die neue Datei in das Repository übernommen wird. Dadurch wird auch automatisch die erste Ausführung von GitHub Actions ausgelöst, sofern bis zu diesem Punkt alles korrekt eingerichtet wurde.

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

[![Build Status](https://github.com/GITHUB-USERNAME/REPO-NAME/workflows/Tests/badge.svg)](https://github.com/GITHUB-USERNAME/REPO-NAME/actions)
In diesem Code muss 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

[![Build Status](https://github.com/LukeWCS/lf-who-was-here-2/workflows/Tests/badge.svg)](https://github.com/LukeWCS/lf-who-was-here-2/actions)
Dadurch wird ein "badge" (Abzeichen/Plakette) innerhalb der Readme eingebunden, wodurch der Status der letzten Prüfung angezeigt wird. Die Aktualisierung der Plakette kann übrigens nach einer Prüfung immer ein paar Minuten dauern.

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-ignore
6. Travis CI deaktivieren

Die 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.
  1. Den Ordner travis und die Datei .travis.yml löschen. Dadurch wird Travis effektiv für dieses Repository deaktiviert.
  2. Sofern bisher eine Travis CI Plakette in der Readme eingefügt war, muss deren Markdown Code natürlich aus der README.md entfernt werden.
Anhang A: Repository Beispiele mit GitHub Actions
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.
Zuletzt geändert von Dr.Death am 01.05.2023 10:14, insgesamt 44-mal geändert.
Grund: Updated: runs-on: ubuntu-20.04 , - php: '7.3'
Möge das Backup mit dir sein. Immer.

Erweiterungen - Infos zur artgerechten Haltung
phpBB Ext Check - Analysesystem für phpBB Erweiterungen (Entwickler Werkzeug)
Benutzeravatar
Dr.Death
Moderator
Moderator
Beiträge: 17395
Registriert: 23.04.2003 08:22
Wohnort: Xanten
Kontaktdaten:

Re: Eine Erweiterung automatisch mit Github Actions testen

Beitrag von Dr.Death »

Vielen Dank für die ausführliche Anleitung. :ugeek:

Konnte sie ohne Probleme in meinem Github Repository einsetzen, klappte auf Anhieb.
Benutzeravatar
Mike-on-Tour
Supporter
Supporter
Beiträge: 1063
Registriert: 13.01.2020 21:09
Kontaktdaten:

Re: Eine Erweiterung automatisch mit Github Actions testen

Beitrag von Mike-on-Tour »

Dem Dank kann ich mich nur anschließen, habe mich heute auch daran versucht und war auf Anhieb erfolgreich. Wer weiß, dass GitHub und ich keine engen Freunde sind, kann gut verstehen, wie hilfreich diese sehr ausführliche Anleitung ist.
Benutzeravatar
LukeWCS
Supporter
Supporter
Beiträge: 2091
Registriert: 15.12.2014 10:19
Kontaktdaten:

Re: Eine Erweiterung automatisch mit Github Actions testen

Beitrag von LukeWCS »

Dr.Death hat geschrieben: 24.04.2021 22:13 Konnte sie ohne Probleme in meinem Github Repository einsetzen, klappte auf Anhieb.
Mike-on-Tour hat geschrieben: 26.04.2021 19:31 habe mich heute auch daran versucht und war auf Anhieb erfolgreich.
Guten Morgen Stefan und Michael

Ich habe euch zitiert, um eine Benachrichtigung zu triggern. Ich würde gerne unsere Repos als Beispiele in die Anleitung aufnehmen, sofern von eurer Seite nichts dagegen spricht. Gerade bei einer Anleitung sind bereits funktionierende Beispiele immer Gold wert.
Möge das Backup mit dir sein. Immer.

Erweiterungen - Infos zur artgerechten Haltung
phpBB Ext Check - Analysesystem für phpBB Erweiterungen (Entwickler Werkzeug)
Benutzeravatar
Dr.Death
Moderator
Moderator
Beiträge: 17395
Registriert: 23.04.2003 08:22
Wohnort: Xanten
Kontaktdaten:

Re: Eine Erweiterung automatisch mit Github Actions testen

Beitrag von Dr.Death »

Von mir aus gerne, kein Problem.
Benutzeravatar
Mike-on-Tour
Supporter
Supporter
Beiträge: 1063
Registriert: 13.01.2020 21:09
Kontaktdaten:

Re: Eine Erweiterung automatisch mit Github Actions testen

Beitrag von Mike-on-Tour »

Gerne, habe auch nichts dagegen.
Benutzeravatar
LukeWCS
Supporter
Supporter
Beiträge: 2091
Registriert: 15.12.2014 10:19
Kontaktdaten:

Re: Eine Erweiterung automatisch mit Github Actions testen

Beitrag von LukeWCS »

Unsere Repos sind jetzt im Anhang A aufgeführt.
Möge das Backup mit dir sein. Immer.

Erweiterungen - Infos zur artgerechten Haltung
phpBB Ext Check - Analysesystem für phpBB Erweiterungen (Entwickler Werkzeug)
Benutzeravatar
Dr.Death
Moderator
Moderator
Beiträge: 17395
Registriert: 23.04.2003 08:22
Wohnort: Xanten
Kontaktdaten:

Re: Eine Erweiterung automatisch mit GitHub Actions testen

Beitrag von Dr.Death »

Ersten Beitrag aktualisiert:

Alt:

Code: Alles auswählen

        runs-on: ubuntu-18.04
Neu:

Code: Alles auswählen

        runs-on: ubuntu-20.04
Alt:

Code: Alles auswählen

                      php: '7.1'
Neu:

Code: Alles auswählen

                      php: '7.3'
Grund der Änderung:

Die Github Runner starten nicht mehr, wenn eine nicht mehr supportete Ubuntu Version verlangt wird.
Benutzeravatar
LukeWCS
Supporter
Supporter
Beiträge: 2091
Registriert: 15.12.2014 10:19
Kontaktdaten:

Re: Eine Erweiterung automatisch mit GitHub Actions testen

Beitrag von LukeWCS »

Dr.Death hat geschrieben: 01.05.2023 10:17 Ersten Beitrag aktualisiert:
Hatte mich gerade gewundert, warum GA im EMP Repo nicht ausgeführt wird und erinnerte mich dann an dein Update hier. Nu klappts auch wieder. :)

Im Original Thema wurde übrigens PHP 7.2 definiert, wobei für EPV PHP 7.3 Maximum ist. Zumindest unter Windows. Hoffen wir mal, das es ein Update für EPV gibt, wäre längst überfällig. Vor allem weil es nur noch eine Frage der Zeit ist, bis PHP 7 nirgends mehr läuft. Mein Hoster hat auch schon angefangen PHP 7 stillzulegen. Ich bin noch nicht betroffen, aber das wird sicher nicht mehr lange dauern.
Möge das Backup mit dir sein. Immer.

Erweiterungen - Infos zur artgerechten Haltung
phpBB Ext Check - Analysesystem für phpBB Erweiterungen (Entwickler Werkzeug)
Antworten

Zurück zu „Extension Bastelstube“