Kontinuierliche Integration mit GitHub Actions einrichten

[Discourse]

Übersicht

Um eine robuste Erweiterung für Discourse zu erstellen, kann es sinnvoll sein, Continuous Integration (CI) in Ihr Plugin oder Ihr Theme-Component zu integrieren. 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 für alle unsere Komponenten verwendet, und wir empfehlen Ihnen, dasselbe zu tun.

Einrichtung

Um automatisierte Workflows für GitHub Actions 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 GitHub Actions ausführen muss. Dies könnten beispielsweise .yml-Dateien für Linting und Tests sein.

Wir haben Vorlagen-Workflows für beide Plugins und Theme-Components erstellt, die Sie nutzen können. Diese sind mit unseren Definitionen für ‘wiederverwendbare Workflows’ hier verbunden.

Im Skelett-Repository der Vorlage können Sie auf GitHub auf die Schaltfläche Diese Vorlage verwenden klicken, um ein Plugin- oder Theme-Component-Repository basierend auf der Vorlage zu erstellen.

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

Plugins: discourse-plugin.yml

Themes und Theme-Components: discourse-theme.yml

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

Voilà! Sie sind bereit! Erstellen Sie einfach einen Commit oder einen PR in Ihrem Repository, und GitHub Actions erkennt die Workflows automatisch und beginnt mit der Ausführung der Jobs.

GitHub Actions zeigt eine Aufschlüsselung jedes Tests an und gibt nach der Ausführung entweder ein oder ein 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, was Ihnen Hinweise darauf geben kann, was mit Ihrem Code nicht stimmt und was behoben werden muss.

Beispiel ansehen

Eigene Tests hinzufügen

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

Für Details dazu, wie man Frontend-Tests mit EmberJS schreibt, siehe:

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

Für weitere Details zum Schreiben von RSpec-Tests mit Rails siehe:

• RSpec - Behavior Driven Development for Ruby

Beispiele

Zu Ihrem Vorteil haben wir einige Beispiele für Plugins und Theme-Components ausgewählt, die eine robuste Testintegration aufweisen:

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

---

Dieses Dokument wird versioniert – schlagen Sie Änderungen auf GitHub vor.

[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.