docs: align English compatibility guide with Chinese version

2026-10-11 11:04:41 +08:00
1 parent 5f5ad058a8
commit e51e2e9996
@@ -0,0 +1,66 @@
+# Gitea 兼容性
+---
+[English](../COMPATIBILITY.md)
+
+此文件描述了 Gitea Mail Templates 与 Gitea 不同版本之间的兼容性。
+
+## 兼容性表
+
+根据所运行的 Gitea 版本选择对应推荐的模板版本。`[PASS]` 表示已记录为兼容的组合，`[PENDING]` 表示尚未完成验证。
+
+> [!NOTE]
+> 历史条目仅反映项目已有的兼容性评估，不代表每次发布都重新测试了每一个补丁版本。
+
+| Gitea 版本 | 推荐模板版本 | 状态 | 说明 |
+|---|---|---|---|
+| 28.1.0 | — | [PENDING] | 等待兼容性验证 |
+| 28.0.0 | **v28.0.0** | [PASS] | Gitea 将邮件函数 `FileSize` 替换为 `FormatByteSize` |
+| 1.27.3 | **v1.27.3** | [PASS] | 全部主题已修复拉取请求推送通知的提交链接 |
+| 1.27.2 | **v1.27.3** | [PASS] | 同号 v1.27.2 模板的 Bloom、Ember、Heritage 存在推送通知缺陷 |
+| 1.27.1 | **v1.27.3** | [PASS] | 较早 v1.0.x 模板使用过时的推送提交字段 |
+| 1.27.0 | — | [PENDING] | Gitea 使用了新的提交数据结构；v1.27.3 可能适用，但未在此版本上验证 |
+| 1.26.4 | **v1.0.1** | [PASS] | — |
+| 1.26.3 | **v1.0.1** | [PASS] | — |
+| 1.26.2 | **v1.0.1** | [PASS] | — |
+| 1.26.1 | **v1.0.1** | [PASS] | — |
+| 1.26.0 | **v1.0.1** | [PASS] | — |
+| 1.25.5 | **v1.0.1** | [PASS] | — |
+| 1.25.0 | **v1.0.1** | [PASS] | — |
+
+> [!NOTE]
+> Gitea 1.24.x 及更早版本使用不同的邮件模板布局，属于 `[UNSUPPORTED]`，Gitea Mail Templates 不再另外支持。v1.0.0 模板标签已由 v1.0.1 替代，不再单独推荐。
+
+## Gitea 历版本对邮件模板影响
+
+此表描述 **Gitea** 的变化，不是本模板仓库的修复记录。“无”表示该 Gitea 版本没有新增相关邮件模板影响；推荐归档见上方兼容性表。
+
+| Gitea | 发布日期 | 邮件模板变化 | 影响 |
+|---|---|---|---|
+| **28.1.0** | 2026-10-06 | [PENDING] | [PENDING] |
+| **28.0.0** | 2026-09-29 | 邮件函数 `FileSize` 改为 `FormatByteSize` （[PR](https://github.com/go-gitea/gitea/pull/#39083)） | **不兼容变更：** 旧的发布附件模板失效 |
+|||引入 templates/mail/base/ （[PR](https://github.com/go-gitea/gitea/pull/#38396)）| **不兼容变更：**旧版本 Gitea 无法直接使用新版本邮件模板 |
+| **1.27.3** | 2026-08-29 | 无 | 无 |
+| **1.27.2** | 2026-08-14 | 无 | 无 |
+| **1.27.1** | 2026-07-27 | 内置推送模板改用 `.UserCommit.GitCommit`（[PR](https://github.com/go-gitea/gitea/pull/38467)） | **不兼容变更：存在既有未修复缺陷** 旧的自定义拉取请求推送模板可能失效 |
+| **1.27.0** | 2026-07-13 | 推送提交数据移至 `.UserCommit.GitCommit`（[ISSUE](https://github.com/go-gitea/gitea/issues/38469)） | **不兼容变更：** 旧的拉取请求推送模板失效 |
+| **1.26.4** | 2026-06-21 | 无 | 无 |
+| **1.26.3** | 2026-06-20 | 无 | 无 |
+| **1.26.2** | 2026-05-20 | 无 | 无 |
+| **1.26.1** | 2026-04-22 | 无 | 无 |
+| **1.26.0** | 2026-04-19 | 无 | 无 |
+| **1.25.5** | 2026-03-10 | 无 | 无 |
+| **1.25.0** | 2025 | 自定义邮件路径及主题和正文格式变化（[PR](https://github.com/go-gitea/gitea/pull/35150)） | **不兼容变更：** 不支持更早的模板布局 |
+| **≤ 1.24.x** | — | 旧的自定义邮件布局 | [UNSUPPORTED] |
+
+## 模板变量参考
+
+各类邮件上下文由官方模板定义。开发时具体的邮件模板和函数和变量请参考官方邮件模板文档 [1](#注释)。
+
+## 翻译键
+
+官方模板引用 `mail.*` 和 `actions.runs.attempt`。基于 AST 的检查覆盖 `.locale.Tr`、`$.locale.Tr` 和 `TrN` 的两个复数键，包括嵌套管道。所有引用键必须存在于锁定的英文目录。
+
+---
+### 注释
+
+[1](#注释): [Mail templates | Gitea Documentation](https://docs.gitea.com/administration/mail-templates/)
@@ -32,7 +32,7 @@ Gitea Mail Template 为自托管的 [Gitea](https://about.gitea.com) 提供多

 ### 选择安装来源

-运行 `gitea --version` 确认部署的 Gitea 实例版本，再按照[兼容矩阵](../COMPATIBILITY.md#compatibility-matrix)选择模板版本。
+运行 `gitea --version` 确认部署的 Gitea 实例版本，再按照[兼容性表](COMPATIBILITY.zh-CN.md#兼容性表)选择模板版本。

 > [!WARNING]
 > 我们不建议直接从源码仓库拉取并构建，因为这些版本还未经过完全测试达到发行可用的水平。如果存在未知的模板参数过时或遗漏可能导致 Gitea 实例启动异常。
@@ -52,7 +52,7 @@ cd tools
 go run . build all
 cd ..
 ```
-构建可用模板时需要依赖于 Gitea 官方仓库的资源文件，以确保来源的一致性。因此该命令会自动下载由`gitea.lock.json` 文件锁定的官方文件，后续构建无需再次下载，使用缓存目录资源即可运行。文件缺失或缓存损坏的处理方式见[更新官方快照](CONTRIBUTING.zh-CN.md#更新官方快照)。
+构建可用模板时需要依赖于 Gitea 官方仓库的资源文件，以确保来源的一致性。因此该命令会自动下载由`gitea.lock.json` 文件锁定的官方文件，后续构建无需再次下载，使用缓存目录资源即可运行。文件缺失或缓存损坏的处理方式见[更新官方快照](#更新官方快照)。

 ### 安装主题