使用 GitHub Actions 设置持续集成

文档 开发者指南
,
1

:mag: 概述

若要为 Discourse 构建一个健壮的扩展，将持续集成（CI）纳入您的插件或主题组件中是明智之举。这将有助于尽早发现错误，并降低代码中出现 bug 的可能性。

使用 GitHub Actions 设置 CI 工作流以自动化构建和测试，是 Discourse 团队在所有组件中采用的方法，我们也建议您照此办理。

:gear: 设置步骤

要为 GitHub Actions 添加自动工作流以进行检测，您需要在仓库的根目录下创建一个 .github/workflows 文件夹。

在 workflows 文件夹内，您可以定义一组 GitHub Actions 需要运行的自动化任务。例如，这些可以是用于代码检查和测试的 .yml 文件。

我们已为 插件 和 主题组件 创建了模板工作流，您可以直接使用。这些模板连接到我们的“可重用工作流”定义 此处。

在模板的骨架仓库中，您可以在 GitHub 上点击 使用此模板 按钮，基于该模板创建插件或主题组件仓库。

或者，如果您已有项目并希望添加工作流，只需将相应的工作流复制到您仓库的 .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

您可以明确提及 https://github.com/discourse/discourse-theme-skeleton，并指出您应该关注它以了解这些文件的更改。

4 个赞
7

希望可重用的工作流能够合并，使这部分不那么重要，因为新创建的存储库将直接使用模板存储库中的工作流。

2 个赞
8

感谢 @pfaffman 和 @Simon_Manning，说得很好。我已经相应地更新了 OP。

4 个赞
9

我已经更新了 OP，以包含使用我们新的“可重用工作流”的说明。现在，我们可以对工作流定义进行的微小调整，自动应用于您的主题/插件，无需任何手动工作。

3 个赞
10

我是否需要做些什么特殊的事情，以便让插件在最新的已通过测试 和 稳定版本上进行测试？

1 个赞
11

plugin skeleton workflow 使用了以下内容，我认为它将针对默认分支 main 进行测试。可重用工作流有一个可选的 core_ref 输入，据我所知，如果没有它，将检出 discourse/discourse 存储库的默认分支。

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

我无法确定这是否真的将其限制为针对 main 进行测试，但如果确实如此，您可以添加一个矩阵策略来针对您想要测试的每个 ref 运行一次。

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

是的，这样就可以了。或者，您也可以手动编写这两个作业，而无需使用矩阵：

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 的所有公共主题/插件，我们会在每次稳定发布时向 discourse-compatibility 添加一个条目以“冻结”它们。这样，我们在开发它们时就不必担心稳定兼容性问题。

5 个赞
13

感谢你们两位。

是的，这可能是最直接的方法。唯一的缺点是它可能会阻碍新功能的（以及新的错误修复）的推出。

2 个赞