使用 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 个赞
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 个赞