Kontinuierliche Integration mit GitHub Actions einrichten

[Discourse]

Übersicht

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

Die Einrichtung eines mit GitHub Actions automatisierten Workflows für Builds und Tests ist ein Ansatz, den das Discourse-Team bei allen unseren Komponenten verfolgt, und wir empfehlen Ihnen, dasselbe zu tun.

Einrichtung

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

Innerhalb des workflows-Ordners können Sie eine Reihe von Automatisierungen definieren, die GitHub Actions ausführen soll. Dies könnten beispielsweise .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 verwenden können. Diese verbinden sich mit unseren „wiederverwendbaren Workflow“-Definitionen hier.

Im Skeleton-Repository der Vorlage können Sie auf GitHub auf die Schaltfläche Use this template klicken, um ein Plugin-/Theme-Komponenten-Repository basierend auf der Vorlage zu erstellen.

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

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 Breaking Changes (z. B. Einführung eines neuen Linters) erhöhen wir die Hauptversion der wiederverwendbaren Workflows, und Sie müssen Ihren Workflow aktualisieren, um auf die neue Version zu verweisen.

Voila! Sie sind fertig! 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 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 Hinweise darauf geben kann, was mit Ihrem Code nicht stimmt und was behoben werden muss.

Beispiel anzeigen

Eigene Tests hinzufügen

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

Details zum Schreiben von Frontend-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 for Ruby

Beispiele

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

Plugin / Komponente	Clientseitige Tests	Serverseitige 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 hier vorschlagen 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.