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 dein Plugin oder dein Theme-Component einzubinden. Dies hilft, Fehler frühzeitig zu erkennen und die Wahrscheinlichkeit von Bugs in deinem 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 all unsere Komponenten verwendet, und wir empfehlen dir, es genauso zu machen.

Einrichtung

Um automatisierte Workflows für GitHub Actions hinzuzufügen, musst du einen .github/workflows-Ordner im Stammverzeichnis deines Repositories erstellen.

Im workflows-Ordner kannst du eine Reihe von Automatisierungen definieren, die GitHub Actions ausführen muss. Dies können beispielsweise .yml-Dateien für Linting und Tests sein.

Wir haben Template-Workflows für Plugins und Theme-Components erstellt, die du verwenden kannst. Diese sind an unsere Definitionen für „wiederverwendbare Workflows“ hier angebunden.

Im Skeleton-Repository des Templates auf GitHub kannst du auf die Schaltfläche Dieses Template verwenden klicken, um ein Plugin- oder Theme-Component-Repository basierend auf dem Template zu erstellen.

Alternativ, falls du bereits ein Projekt hast, zu dem du die Workflows hinzufügen möchtest, kopiere einfach den relevanten Workflow in den .github/workflows/-Ordner deines Repositories:

Plugins: discourse-plugin.yml

Themes und Theme-Components: discourse-theme.yml

Diese Templates sind an eine bestimmte Hauptversion unserer wiederverwendbaren Workflows gebunden. Kleine Verbesserungen, die wir an den Workflows vornehmen, werden automatisch in deinem Theme/Plugin wirksam. Bei abwärtsinkompatiblen Änderungen (z. B. die Einführung eines neuen Linters) erhöhen wir die Hauptversion der wiederverwendbaren Workflows, und du musst deinen Workflow aktualisieren, damit er auf die neue Version verweist.

Voilà! Du bist fertig eingerichtet! Erstelle einfach ein Commit oder einen PR in deinem Repository, und GitHub Actions wird die Workflows automatisch erkennen und mit der Ausführung der Jobs beginnen.

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, erhältst du durch Klicken auf die Details einige Informationen darüber, was schiefgelaufen ist, was dir Hinweise darauf geben kann, was mit deinem 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 du Tests für dein Plugin oder dein Theme-Component schreibst.

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 deinem Vorteil haben wir einige Beispiele für Plugins und Theme-Components ausgewählt, bei denen robuste Tests integriert sind:

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 verwaltet - Vorschläge für Änderungen auf GitHub.

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