GitHub Actions を使用した継続的インテグレーションのセットアップ

ドキュメント 開発者ガイド
,
1

:mag: 概要

Discourse の堅牢な拡張機能を構築するには、プラグインまたはテーマコンポーネントに継続的インテグレーション (CI) を含めることが賢明です。これにより、エラーを早期に検出し、コード内のバグの可能性を減らすことができます。

ビルドとテストを自動化するために GitHub Actions を使用して継続的インテグレーション (CI) ワークフローを設定することは、Discourse チームがすべてのコンポーネントで使用しているアプローチであり、皆様にも同じことをお勧めします。

:gear: 設定方法

GitHub Actions が検出するための自動化されたワークフローを追加するには、リポジトリのルートディレクトリに .github/workflows フォルダーを作成する必要があります。

workflows フォルダー内では、GitHub Actions が実行する必要のある一連の自動化を定義できます。たとえば、これらはリンティングやテストのための .yml ファイルになる可能性があります。

私たちは、プラグイン と テーマコンポーネント の両方のテンプレートワークフローを作成しましたので、これらを利用できます。これらは、こちら の「再利用可能なワークフロー」定義に接続されています。

テンプレートのスケルトンリポジトリでは、GitHub 上で Use this template ボタンをクリックして、テンプレートに基づいたプラグイン/テーマコンポーネントリポジトリを作成できます。

あるいは、すでにワークフローを追加したいプロジェクトがある場合は、関連するワークフローをリポジトリの .github/workflows/ フォルダーにコピーするだけです。

:electric_plug: プラグイン: discourse-plugin.yml

:jigsaw: テーマとテーマコンポーネント: discourse-theme.yml

:point_up: これらのテンプレートは、再利用可能なワークフローの特定のメジャーバージョンに固定されています。ワークフローに加えられた小さな改善は、テーマ/プラグインに自動的に反映されます。破壊的変更（例：新しいリンターの導入）があった場合、再利用可能なワークフローのメジャーバージョンが更新されるため、ワークフローを新しいバージョンを指すように更新する必要があります。

:tada: 完成です！セットアップは完了です！リポジトリにコミットまたは PR を作成するだけで、GitHub Actions がワークフローを自動的に検出し、ジョブの実行を開始します。

GitHub Actions は、各テストの内訳を表示し、実行後、テストが合格したか失敗したかに応じて :white_check_mark: または :x: を示します。

テストが失敗した場合、詳細をクリックすると、何が失敗したかについての情報が表示され、コードのどこに問題があり、何を修正する必要があるかについてのヒントが得られる場合があります。

例を見る

example failure
example failure2192×1018 250 KB

:white_check_mark: 独自のテストを追加する

プラグインとコンポーネントのテストが効果的に機能するためには、プラグインまたはテーマコンポーネントのテストを作成することが重要です。

EmberJS を使用したフロントエンドテストの記述方法の詳細については、以下を参照してください。

Rails を使用したテスト RSpec テストの記述方法の詳細については、以下を参照してください。

:bulb: 例

皆様の参考のために、堅牢なテストが統合されているプラグインとテーマコンポーネントのいくつかの例を厳選しました。

プラグイン / コンポーネント クライアント側テスト サーバー側テスト
Assign :link: フォルダーを表示 :link: フォルダーを表示
Calendar :link: フォルダーを表示 :link: フォルダーを表示
Reactions :link: フォルダーを表示 :link: フォルダーを表示
Right Sidebar Blocks :link: フォルダーを表示
Tag Icons :link: フォルダーを表示
Table Builder :link: フォルダーを表示

このドキュメントはバージョン管理されています - 変更提案は github で行ってください。

「いいね！」 15
How could a CI workflow for unofficial plugins be implemented?
Unexpected error in Discourse Plugin CI
6

GitHub - discourse/discourse-theme-skeleton: Template for Discourse themes を明示的に言及し、それらのファイルの変更に注意するためにウォッチする必要があることを指摘するとよいでしょう。

「いいね！」 4
7

再利用可能なワークフローがマージされ、テンプレートから作成された新しいリポジトリがテンプレートリポジトリから直接ワークフローを使用するようになれば、この部分は関連性が低くなることが期待されます。

「いいね！」 2
8

@pfaffman、@Simon_Manning、ありがとうございます。良い点ですね。OPをそれに応じて更新しました。

「いいね！」 4
9

OPを更新し、新しい「再利用可能なワークフロー」の使用方法に関する説明を追加しました。ワークフロー定義に加えるマイナーな変更は、手作業なしでテーマ/プラグインに自動的に適用できるようになります。

「いいね！」 3
10

最新の tests-passed および stable に対してプラグインをテストするために、何か特別なことをする必要がありますか？

「いいね！」 1
11

プラグインスケルトンワークフローは以下を使用しており、これはデフォルトのブランチ、つまりmainに対してテストされると思います。再利用可能なワークフローにはオプションのcore_ref入力があり、私の知る限り、それがない場合、discourse/discourseリポジトリのデフォルトブランチがチェックアウトされます。

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

これが実際にmainに限定してテストされるかどうかは断言できませんが、もしそうであれば、テストしたい各リファレンスに対して1回実行するマトリックス戦略を追加できます。

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

はい、これで大丈夫でしょう。または、マトリックスを使用せずに、2つのジョブを手動で記述することもできます。

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

ただし、注意点として、これらのジョブは .discourse-compatiblity をチェックしません。そのため、このファイルを使用せず、同時に main と stable の両方との互換性が必要なプラグインでのみ、これを行う価値があります。

CDCK のすべての公開テーマ/プラグインでは、ディスコース互換性エントリを追加して、すべての安定リリースでそれらを「フリーズ」します。そうすれば、開発中に安定互換性を気にする必要がなくなります。

「いいね！」 5
13

お二人ともありがとうございます。

ええ、おそらくそれが最も簡単なアプローチでしょう。唯一の欠点は、機能（および新しいバグ修正）が遅れる可能性があることです。

「いいね！」 2