使用 GitHub Actions 设置持续集成

文档 开发者指南
,
1

:mag: 概述

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

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

:gear: 设置方法

为了添加用于检测的 GitHub Actions 自动化工作流，你需要在仓库的根目录中创建一个 .github/workflows 文件夹。

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

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

在模板的骨架仓库中，你可以在 GitHub 上点击 Use this template 按钮，基于该模板创建插件/主题组件仓库。

或者，如果你已经有一个想要添加工作流的项目，只需将相关的工作流文件复制到你的仓库的 .github/workflows/ 文件夹中即可：

:electric_plug: 插件： discourse-plugin.yml

:jigsaw: 主题和主题组件： discourse-theme.yml

:point_up: 这些模板锁定到我们可复用工作流的特定主要版本。我们对工作流所做的微小改进将自动在你的主题/插件中生效。对于破坏性变更（例如引入新的 linter），我们会提升可复用工作流的主要版本号，你需要更新你的工作流以指向新版本。

:tada: 完成！你已设置好一切！只需向你的仓库创建一个提交 (commit) 或 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 个赞