Continuous Integration mit GitHub Actions einrichten

[Discourse]

Überblick

Um eine robuste Erweiterung für Discourse zu erstellen, kann es sinnvoll sein, Continuous Integration (CI) in Ihr Plugin oder Theme-Komponente aufzunehmen. Dies hilft, Fehler frühzeitig zu erkennen und die Wahrscheinlichkeit von Bugs in Ihrem Code zu verringern.

Die Einrichtung eines CI-Workflows mit GitHub Actions zur Automatisierung von Builds und Tests ist ein Ansatz, den das Discourse-Team bei allen unseren Komponenten verwendet, und wir empfehlen Ihnen, dasselbe zu tun.

Einrichtung

Um automatisierte Workflows für GitHub Actions zur Erkennung hinzuzufügen, müssen Sie einen Ordner .github/workflows im Stammverzeichnis Ihres Repositories erstellen.

Im Ordner workflows können Sie eine Reihe von Automatisierungen definieren, die von GitHub Actions ausgeführt werden müssen. Beispielsweise könnten dies .yml-Dateien für Linting und Tests sein.

Wir haben Vorlagen-Workflows sowohl für Plugins als auch für Theme-Komponenten erstellt, die Sie nutzen können. Diese verbinden sich mit unseren Definitionen für ‘wiederverwendbare Workflows’ hier.

Im Skelett-Repository der Vorlage können Sie auf GitHub auf die Taste Diese Vorlage verwenden klicken, um ein Plugin-/Theme-Komponenten-Repository basierend auf der Vorlage zu erstellen.

Alternativ können Sie, falls Sie bereits ein Projekt haben, dem Sie die Workflows hinzufügen möchten, einfach den entsprechenden Workflow in den Ordner .github/workflows/ Ihres Repositories kopieren:

Plugins: discourse-plugin.yml

Themes und Theme-Komponenten: discourse-theme.yml

Diese Vorlagen sind an eine bestimmte Hauptversion unserer wiederverwendbaren Workflows gebunden. Kleine Verbesserungen, die wir an den Workflows vornehmen, treten automatisch in Ihrem Theme/Plugin in Kraft. Bei breaking changes (z. B. Einführung eines neuen Linters) erhöhen wir die Hauptversion der wiederverwendbaren Workflows, und Sie müssen Ihren Workflow auf die neue Version aktualisieren.

Voila! Sie sind bereit! Erstellen Sie einfach einen Commit oder eine PR in Ihr Repository, und GitHub Actions erkennt die Workflows automatisch und startet die Jobs.

GitHub Actions zeigt eine Aufschlüsselung jedes Tests an und gibt nach dem Ausführen entweder ein oder an, je nachdem, ob der Test bestanden oder fehlgeschlagen ist.

Wenn ein Test fehlgeschlagen ist, erhalten Sie durch Klicken auf die Details einige Informationen darüber, was fehlgeschlagen ist. Dies kann Ihnen Hinweise darauf geben, was an Ihrem Code falsch ist und was behoben werden muss.

Beispiel ansehen

Eigene Tests hinzufügen

Damit Tests für Plugins und Komponenten effektiv funktionieren, ist es wichtig, dass Sie Tests für Ihr Plugin oder Ihre Theme-Komponente schreiben.

Details zum Schreiben von Front-End-Tests mit EmberJS finden Sie unter:

• Write acceptance tests and component tests for Ember code in Discourse
• Introduction - Testing - Ember Guides

Weitere Details zum Schreiben von RSpec-Tests mit Rails finden Sie unter:

• RSpec - Behavior Driven Development für Ruby

Beispiele

Zu Ihrem Nutzen haben wir einige Beispiele für Plugins und Theme-Komponenten ausgewählt, die robuste Tests integriert haben:

Plugin / Komponente	Client-seitige Tests	Server-seitige Tests
Assign	Ordner anzeigen	Ordner anzeigen
Calendar	Ordner anzeigen	Ordner anzeigen
Reactions	Ordner anzeigen	Ordner anzeigen
Right Sidebar Blocks	Ordner anzeigen
Tag Icons	Ordner anzeigen
Table Builder	Ordner anzeigen

---

Dieses Dokument wird versioniert – Änderungen können auf GitHub vorgeschlagen werden.

[pfaffman (Jay Pfaffman)]

Sie könnten GitHub - discourse/discourse-theme-skeleton: Template for Discourse themes explizit erwähnen und darauf hinweisen, dass Sie es beobachten sollten, um Änderungen an diesen Dateien zu bemerken.

[Simon_Manning]

@pfaffman

Sie sollten es sich ansehen, um Änderungen in diesen Dateien zu bemerken

Hoffentlich können die wiederverwendbaren Workflows zusammengeführt werden, wodurch dieser Teil weniger relevant wird, da neue Repositories, die aus der Vorlage erstellt werden, die Workflows direkt aus dem Vorlagen-Repository verwenden.

[keegan (Keegan George)]

Danke @pfaffman und @Simon_Manning, gute Punkte. Ich habe die OP entsprechend aktualisiert.

[david (David Taylor)]

Ich habe die OP aktualisiert, um Anweisungen für die Verwendung unserer neuen „wiederverwendbaren Workflows“ aufzunehmen. Kleinere Änderungen, die wir an den Workflow-Definitionen vornehmen, können nun automatisch auf Ihre Themes/Plugins angewendet werden, ohne dass manuelle Arbeit erforderlich ist.

Wir haben Vorlagen-Workflows sowohl für Plugins als auch für Theme-Komponenten erstellt, die Sie verwenden können. Diese verbinden sich mit unseren „wiederverwendbaren Workflow“-Definitionen hier.

…

Plugins: discourse-plugin.yml

Themes und Theme-Komponenten: discourse-theme.yml

\u003e Diese Vorlagen sind auf eine bestimmte Hauptversion unserer wiederverwendbaren Workflows gesperrt. Kleinere Verbesserungen, die wir an den Workflows vornehmen, werden automatisch in Ihrem Theme/Plugin wirksam. Bei Breaking Changes (z. B. Einführung eines neuen Linters) werden wir die Hauptversion der wiederverwendbaren Workflows erhöhen, und Sie müssen Ihren Workflow aktualisieren, um auf die neue Version zu verweisen.

[merefield (Robert)]

Muss ich etwas Besonderes tun, um ein Plugin gegen die neuesten Tests bestanden und stabile zu testen?

[Simon_Manning]

Der Plugin-Skeleton-Workflow verwendet Folgendes, was meiner Meinung nach gegen den Standard-Branch, also main, testet. Der wiederverwendbare Workflow hat eine optionale core_ref-Eingabe und soweit ich das beurteilen kann, wird ohne diese der Standard-Branch des discourse/discourse-Repositorys ausgecheckt.

jobs:
  ci:
    uses: discourse/.github/.github/workflows/discourse-plugin.yml@v1

Ich kann nicht sagen, ob das tatsächlich auf das Testen gegen main beschränkt ist oder nicht, aber wenn ja, könnten Sie eine Matrixstrategie hinzufügen, um für jeden zu testenden Ref einmal auszuführen.

jobs:
  ci:
    strategy:
      matrix:
        target: [tests-passed, stable]
    uses: discourse/.github/.github/workflows/discourse-plugin.yml@v1
    with:
      core_ref: ${{ matrix.target }}

[david (David Taylor)]

Ja, das sollte es tun. Oder Sie können die beiden Jobs manuell schreiben, ohne eine Matrix zu verwenden:

name: Discourse Plugin

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  ci:
    uses: discourse/.github/.github/workflows/discourse-plugin.yml@v1

  ci-stable:
    uses: discourse/.github/.github/workflows/discourse-plugin.yml@v1
    with:
      core_ref: stable

Es ist jedoch erwähnenswert: Diese Jobs überprüfen nicht .discourse-compatiblity. Dies lohnt sich also nur bei Plugins, die diese Datei nicht verwenden und gleichzeitig mit main und stable kompatibel sein müssen.

Für alle öffentlichen Themes/Plugins von CDCK fügen wir einen Eintrag zu discourse-compatibility hinzu, um sie bei jeder stabilen Version ‘einzufrieren’. Dann müssen wir uns bei der Entwicklung keine Sorgen um die stabile Kompatibilität machen.

[merefield (Robert)]

Vielen Dank euch beiden.

@david

Für alle öffentlichen Themes/Plugins von CDCK fügen wir einen Eintrag zu discourse-compatibility hinzu, um sie bei jeder stabilen Veröffentlichung zu „einfrieren“.

Ja, das ist wahrscheinlich der direkteste Ansatz. Der einzige Nachteil ist, dass er potenziell Funktionen (und neue Fehlerbehebungen) zurückhält.