使用 GitHub Actions 设置持续集成

文档 开发者指南
,
1

:mag: 概述

要为 Discourse 构建一个健壮的扩展，明智的做法是在插件或主题组件中包含持续集成 (CI)。这将有助于及早发现错误，并减少代码中出现错误的几率。

使用 GitHub Actions 设置持续集成 (CI) 工作流程以实现构建和测试自动化是 Discourse 团队在其所有组件上使用的一种方法，我们建议您也这样做。

:gear: 设置

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

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

我们已经为 插件 和 主题组件 创建了模板工作流程供您使用。它们连接到我们在此处的“可重用工作流程”定义 here。

在模板的骨架仓库中，您可以在 GitHub 上点击 \u003ckbd\u003eUse this template\u003c/kbd\u003e 按钮，根据模板创建插件/主题组件仓库。

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

:electric_plug: 插件: discourse-plugin.yml

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

:point_up: 这些模板锁定在我们可重用工作流程的特定主要版本。我们对工作流程所做的微小改进将自动在您的主题/插件中生效。对于破坏性更改（例如引入新的代码检查器），我们将提高可重用工作流程的主版本号，您需要更新工作流程以指向新版本。

:tada: 瞧！您已全部设置完毕！只需向您的仓库创建一个提交或一个 \u003cabbr title="Pull Request"\u003ePR\u003c/abbr\u003e，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: 查看文件夹

\u003csmall\u003e此文档是版本控制的 - 在 github 上建议更改。\u003c/small\u003e

\u003c!-- START DOCS ASSET MAP
[
{
"local_path": "/assets/ci-with-github-actions-1.png",
"local_sha1": "c3fb59eeb13645670b751959d13cdf8e423e0fcf",
"remote_short_url": "upload://imziUfvg1AloA7IQ5jXMyn85Ngu.png"
}
]
END DOCS ASSET MAP –\u003e

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