为旧版 Discourse 安装锁定插件和主题版本（d-compat 分支）

[Discourse]

背景

主题和插件开发者通常希望针对 Discourse 的 latest 版本进行开发，而无需担心向后兼容性。但运行旧版 Discourse 的网站仍然需要能够正常工作的主题/插件版本。

为了弥合这一差距，可以告知 Discourse 检出主题/插件的旧版“固定”版本。有两种机制可实现此目的，按以下顺序检查：

1. 主题/插件仓库中的 d-compat/<YYYY>.<M> Git 分支（主要方法——推荐用于所有新固定版本）。
2. 仓库根目录中的 .discourse-compatibility YAML 文件（原始机制，仍作为后备方案支持）。

如果两者都存在，则分支优先。

d-compat/<YYYY>.<M> 分支系统

Discourse 发布使用基于日期的版本号，如 2025.5、2025.6 等。当 Discourse 从 Git 更新插件或主题时，它会询问仓库：「您是否有与我版本匹配的名为 d-compat/<YYYY>.<M> 的分支？」（例如，针对 Discourse 2025.5.x，分支名为 d-compat/2025.5）。如果有，Discourse 将检出该分支的最新提交，而不是 main 分支。

此查找仅在本地检出位于仓库的默认分支时运行。如果您已故意固定到其他分支，则跳过 d-compat 逻辑，您的固定设置将被尊重。

要使用此系统支持旧版 Discourse：

1. 从一个已知在该版本上正常工作的提交创建名为 d-compat/<YYYY>.<M> 的分支（例如 git checkout -b d-compat/2025.5 <commit>）。
2. 将其推送到 origin。您可能希望保护该分支以防意外删除。
3. 将任何反向移植（backport）提交合并到该分支。运行 2025.5.x 的 Discourse 实例将在下次更新时自动获取这些提交；运行更新版 Discourse 的实例将继续跟踪默认分支。

使用分支时，您完全不需要触碰 .discourse-compatibility 文件。

自动创建分支（create-d-compat-branch.yml）

实际上，您很少需要手动创建这些分支。默认的主题和插件骨架包含一个 d-compat-branch.yml 工作流，该工作流每天运行，检查 Discourse 核心是否有新版本，并在需要时推送匹配的 d-compat/<YYYY>.<M> 分支。

如果您的仓库是从旧版骨架副本创建的，只需将 d-compat-branch.yml 文件复制到您的 .github/workflows 目录即可使其生效。

将修复反向移植到 d-compat 分支

当您在默认分支上完成修复，且该修复也需要应用到运行旧版 Discourse 的网站时：

1. 从目标 d-compat 分支创建新分支，并 cherry-pick 该修复：

   git fetch origin
   git checkout -b backport/my-fix-2025.5 origin/d-compat/2025.5
   git cherry-pick <commit-sha>
   git push -u origin backport/my-fix-2025.5
   

2. 打开一个 PR，将 d-compat/2025.5 作为基础分支（而非 main）。像处理其他 PR 一样对其进行审查和合并。

3. 对每个需要该修复的旧版 d-compat/<YYYY>.<M> 分支重复上述步骤。

运行 2025.5.x 的网站将在下次更新时获取已合并的提交。

旧版后备方案：`.discourse-compatibility` 文件

如果不存在匹配的 d-compat 分支，Discourse 将回退到仓库根目录中的 YAML .discourse-compatibility 文件，该文件将 Discourse 版本映射到插件/主题的 Git 引用：

< 3.2.0.beta2-dev: abcde

Discourse 会选择与当前运行的核心版本匹配的最低条目，因此任何运行 < 3.2.0.beta2-dev 的用户都将检出提交 abcde。使用 <（或旧版的 <=，未指定运算符时的默认值）来指定版本边界。仅在基于分支的系统无法表达您的需求时才使用此方法。

---

本文档受版本控制——如有修改建议，请 在 GitHub 上提出。

[NateDhaliwal]

如果版本是 \u003c 3.5.0.beta8-dev，它会包含 3.5.0 吗？

[david (David Taylor)]

3.5.0 被认为“高于”预发布版本“3.5.0.beta8-dev”。

您始终可以在 Ruby 控制台中尝试比较：

> Gem::Version.new("3.5.0") < Gem::Version.new("3.5.0.beta8-dev")
=> false

[NateDhaliwal]

明白了。感谢您的解释！

[david (David Taylor)]

本文档已更新，以描述来自 RFC: A new versioning strategy for Discourse 的新 d-compat/* 策略，该策略现已可供使用。