Einrichtung der kontinuierlichen Integration mit GitHub Actions

[Discourse]

Übersicht

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

Das Einrichten 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 zur Erkennung hinzuzufügen, müssen Sie einen Ordner namens .github/workflows im Stammverzeichnis Ihres Repositorys erstellen.

Innerhalb des workflows-Ordners können Sie 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 Vorlagen-Workflows für Plugins und 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/eine Theme-Komponenten-Repository basierend auf der Vorlage zu erstellen.

Alternativ können Sie, wenn Sie bereits ein Projekt haben, zu dem Sie die Workflows hinzufügen möchten, einfach den entsprechenden Workflow in den Ordner .github/workflows/ Ihres Repositorys 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, 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.

Voilà! Sie sind bereit! Erstellen Sie einfach einen Commit oder einen Pull Request (PR) für Ihr 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 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.

Einzelheiten 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 Ihrer Information haben wir einige Beispiele für Plugins und Theme-Komponenten ausgewählt, die robuste Tests integriert haben:

Plugin / Komponente	Client-seitige 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 - 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.