chore: refresh docs and adapt workflows for Gitea

2026-10-09 22:02:33 +08:00
1 parent fec3ace600
commit f4d96de79e
@@ -1,79 +1,130 @@
-# 贡献指南 — Gitea 邮件模板
+# 贡献指南

-## 添加主题
+[English](../CONTRIBUTING.md) · [项目概览](README.zh-CN.md) · [兼容性](../COMPATIBILITY.md)

-1. 执行 `cd tools && go run . create <名称>`，创建共享框架主题。
-2. 编辑 `themes/<名称>/theme.json` 和 `theme.css`。
-3. 在 `tools/` 中运行 `go run . upstream prepare`、`go test ./...` 和 `go run . preview all`。
-4. 检查英文、简体中文及另一种官方语言的桌面/移动端预览，随 PR 提交截图。
+欢迎改进主题、工具、测试、文档和翻译。本指南介绍当前源码架构的开发流程；安装和版本选择请参阅 [README](README.zh-CN.md#安装)。

-主题名称以小写字母开头，可包含小写字母、数字和连字符。主题只包含 `theme.json` 与 `theme.css`。新主题默认使用 `framed` 模式及 `standard` 框架布局；`layout` 选择共享框架中的结构预设。可选的 `shared` 模式仅注入 CSS，不添加框架控件。
+## 本地开发

-页头、操作按钮、失效提示/备用链接、侧栏和页脚统一由 `framework/mail/base/` 提供；结构预设位于 `framework/layouts/`，均属于框架，而非主题维护的邮件模板。`tools/builder/framework.go` 是唯一的官方操作值/翻译对齐层。通知分支、主题行、附件及上下文链接来自下载的官方模板，不得复制到各主题中。
-
-## 设计规范
-
- 主题仅定义展示样式，共享框架使用官方邮件值与翻译组织可复用控件。
- 主题使用兼容邮件客户端的 CSS，框架负责展示结构；主题 CSS 不加载外部资源、不生成文字、不隐藏官方内容。框架引用实例托管的 Logo 是有意保留的图片引用。
- 片段校验允许展示性的 table、tr、td、div、span 等节点及展示属性，检查桌面及 390px 移动端布局。
- 尽可能测试 Gmail、Outlook、Apple Mail；浏览器预览不能模拟所有客户端的 CSS 支持。
- 忠于原主题的配色、字体、边框、页头、按钮/备用链接及布局，不使用通用卡片或新增装饰替代既有设计。
- 画廊截图使用 PNG，单张最多 50 KiB，建议 10–20 KiB。截图须来自当前源码构建，并关闭浮动信息面板。
-
-## 更新官方快照
-
-源码仅保留工具生成的 `gitea.lock.json`，记录稳定 Gitea 28+ 标签、不可变提交及文件校验值。官方模板、语言 JSON、图标、许可证和适配参考实现均下载到被忽略的 `build/upstream/`，不在仓库中维护副本。
-
-### 命令参考
-
-以下命令均在 `tools/` 执行。三个子命令都支持 `--root <仓库根目录>`，默认值为相对当前工作目录的 `..`；参数放在子命令之后，含空格的路径须加引号。
-
-```powershell
-# 在 tools/ 中显式指定仓库根目录：
-go run . upstream verify --root "D:\Work\Development\WebSites\GiteaMailTemplates"
-```
-
-| 命令 | 用途 | 联网与写入行为 |
-|---|---|---|
-| `go run . upstream prepare` | 根据仓库锁文件准备精确匹配的输入 | 缓存不存在时按锁定提交下载，验证 SHA-256 后创建 `build/upstream/`；缓存存在时离线校验。不修改根锁文件。 |
-| `go run . upstream verify` | 对照根锁文件检查已有缓存 | 离线、只读，不下载；输出 `[PASS]` 及非英文缺键的 `[FALLBACK]` 列表。 |
-| `go run . upstream sync --tag vX.Y.Z` | 显式选择上游版本 | 通过 GitHub API 解析标签，按提交下载并校验快照，替换缓存并生成 `gitea.lock.json`。仅接受主版本不小于 28 的稳定 `vX.Y.Z` 标签。 |
-
-这些命令不支持隐式 `latest`、读取本地 Gitea 克隆、令牌参数或认证环境变量。`sync` 使用 `api.github.com`，首次 `prepare` 与 `sync` 下载使用 `raw.githubusercontent.com`；网络错误与 API 限流会报错，不会自动换版本。即使快照检查离线，Go 工具链与模块仍可能需要单独联网下载。
-
-### 已有克隆与离线使用
+使用 **Go 1.24 或更高版本**。从仓库根目录开始，准备依赖和锁定的官方文件，再运行检查并生成预览：

 ```bash
 cd tools
 go mod download
 go run . upstream prepare
-go run . upstream verify
 go test ./...
 go run . preview all
 ```

-`build all`、`preview all` 和 `dev` 会自动准备输入，但仍要求根锁文件存在。缓存完整且 Go 工具链/依赖已安装后可离线构建。`verify` 检查官方输入、适配参考实现哈希和官方英文键；框架新增键与操作锚点由构建和渲染检查，因此单独通过 `verify` 不代表兼容性验证完成。
+在浏览器中打开 `preview/index.html`，或在 `tools/` 中运行 `go run . dev`，访问 [http://127.0.0.1:3456](http://127.0.0.1:3456) 使用实时预览。开发服务器监听主题、框架、锁文件与缓存、预览测试数据的变化。
+
+CLI 使用 urfave/cli 和 x/net HTML 解析器。文档与打包检查使用 Python 3.11 或更高版本；只有浏览器检查需要 Node.js 和 `tools/qa` 中的依赖。
+
+### 常用命令
+
+以下命令均在 `tools/` 中执行。带有位置参数时，将选项放在位置参数之前。
+
+| 命令 | 用途 |
+|---|---|
+| `go run . list` | 列出可用主题 |
+| `go run . create my-theme` | 创建主题元数据和 CSS |
+| `go run . build my-theme` | 生成指定主题的安装模板 |
+| `go run . build all` | 生成全部主题 |
+| `go run . preview all` | 构建全部主题并渲染所有官方语言 |
+| `go run . dev` | 在端口 3456 启动开发服务器 |
+| `go run . dev --port 3457` | 指定其他本地端口 |
+| `go run . delete my-theme` | 删除指定主题的源码目录 |
+
+`build` 将模板写入 `build/themes/<名称>/mail/`，并在 `build.json` 中记录文件和源码哈希。`preview` 同时完成构建，随后写入 `preview/rendered.js` 和 `preview/rendered/<语言>.js`。这些生成文件和下载的官方文件均被 Git 忽略，无需随贡献提交。
+
+## 添加主题
+
+1. 在 `tools/` 中运行 `go run . create my-theme`。
+2. 编辑 `themes/my-theme/theme.json` 和 `theme.css`。
+3. 在 `tools/` 中运行 `go test ./...` 和 `go run . preview all`。
+4. 检查英文、简体中文及至少另一种官方语言的桌面与移动端布局，在拉取请求中附上截图。
+
+主题名称以小写字母开头，可包含小写字母、数字和连字符。主题目录只包含 `theme.json` 和 `theme.css`。
+
+```json
+{
+  "name": "my-theme",
+  "description": "主题的简短说明",
+  "mode": "framed",
+  "layout": "standard"
+}
+```
+
+| 模式 | 生成的展示结构 |
+|---|---|
+| `framed` | 使用共享控件和框架布局，由主题 CSS 定义样式。新主题默认使用此模式及 `standard` 布局。 |
+| `shared` | 在官方页头片段中加入 CSS，并保留官方页脚片段；不增加框架控件或各类邮件的覆盖模板。 |
+
+### 共享框架
+
+页头、操作按钮、备用链接、侧栏和页脚位于 `framework/mail/base/`。布局预设位于 `framework/layouts/`，`framed` 主题可通过可选的 `layout` 字段选择预设。配色、字体和间距由主题 CSS 定义。
+
+`tools/builder/framework.go` 将官方操作值和翻译键适配到共享控件。通知条件、主题行、附件和上下文链接由官方模板定义。控件或布局结构的修改应放在框架中，使各主题使用同一套适配逻辑。
+
+布局片段组合后必须形成标签配对完整的展示结构。`__HEADER__` 插入共享页头，`__MAIL_TYPE__` 展开为发现的邮件 ID，页脚片段中的 `__SIDEBAR__` 插入共享侧栏。部署模板的 Logo 使用 `{{AppUrl}}assets/img/favicon.png`；生成的预览数据嵌入下载的图标，供离线显示。
+
+## 设计规范
+
+- 使用兼容邮件客户端的 CSS。主题 CSS 不得加载外部资源、生成文字或隐藏官方内容。
+- 布局片段使用展示性标记。校验器接受 `table`、`tbody`、`tr`、`td`、`div`、`span` 及支持的展示属性。
+- 修改已有主题时，保留其配色、字体、边框、页头、按钮和布局特征。
+- 检查桌面和 390px 移动端预览，覆盖长文本和长 URL。条件允许时测试 Gmail、Outlook 和 Apple Mail；浏览器预览不能模拟邮件客户端。
+- 画廊图片使用 PNG，单张不超过 50 KiB，建议为 10–20 KiB。按[截图指南](images/README.md)保持截图一致。
+
+## 更新官方快照
+
+`gitea.lock.json` 记录稳定的 Gitea 28+ 标签、对应提交和每个文件的 SHA-256。官方邮件模板、语言文件、图标、许可证和已评审的适配参考源码下载到 `build/upstream/`。仓库仅提交生成的根锁文件，不维护官方文件副本。
+
+### 命令参考
+
+在 `tools/` 中执行。每个上游子命令均支持 `--root <仓库根目录>`，默认值为相对当前工作目录的 `..`。参数放在子命令之后，包含空格的路径需要加引号：
+
+```powershell
+go run . upstream verify --root "C:\Projects\GiteaMailTemplates"
+```
+
+| 命令 | 行为 |
+|---|---|
+| `go run . upstream prepare` | 读取根锁文件。缓存不存在时下载并校验对应文件；已有缓存则离线校验。不修改根锁文件。 |
+| `go run . upstream verify` | 对照根锁文件离线、只读检查已有缓存。输出 `[PASS]`，并以 `[FALLBACK]` 列出非英文语言缺少的键。 |
+| `go run . upstream sync --tag vX.Y.Z` | 通过 GitHub API 解析明确指定的稳定 Gitea 28+ 标签，下载并校验文件，然后替换缓存并生成根锁文件。 |
+
+`sync` 使用 `api.github.com`，文件下载使用 `raw.githubusercontent.com`。这些命令不接受本地 Gitea 克隆、认证令牌或隐式的 `latest` 版本。网络错误和 API 限流会中止操作；Go 工具链或模块可能仍需单独联网下载。
+
+### 已有克隆与离线使用
+
+`build`、`preview` 和 `dev` 会自动准备输入，需要已提交的根锁文件，并在使用缓存前完成校验。缓存、Go 工具链和依赖齐备后，可以离线构建。
+
+需要单独检查缓存时，使用 `upstream verify`。它校验官方文件哈希、已评审的适配参考源码，以及官方模板引用的英文翻译键。构建和渲染还会检查框架翻译键及主要操作链接的锚点，因此缓存校验只是兼容性测试的一部分。

 ### 锁文件缺失与显式更新版本

-缺少 `gitea.lock.json` 时，`prepare`、`verify`、构建与预览均在读取锁文件时失败，即使 `build/upstream/lock.json` 仍在也不会代用。普通源码克隆应恢复受版本控制的根锁文件；有意首次初始化时，`sync` 不要求已有根锁文件：
+已有克隆缺少 `gitea.lock.json` 时，应恢复受版本控制的文件。`build/upstream/lock.json` 中的副本不能替代根锁文件。需要有意初始化锁文件时，执行：

 ```bash
 cd tools
-# 当前源码基线；显式初始化，不是发布操作：
 go run . upstream sync --tag v28.0.0
 go run . upstream verify
 go test ./...
 go run . preview all
 ```

-评审其它版本时显式替换标签，例如此处仍为 [PENDING] 的 `v28.1.0`。检查生成的锁文件差异，对齐共享框架与测试数据，执行全部检查及同版本实例冒烟测试后，再更新兼容性文档。`sync` 不构建主题、不更新 Markdown、不创建 Git 标签、不提交、不推送，也不发布。仅缓存缺失时不应使用它。
+评审其他版本时，明确指定对应标签。检查锁文件差异，按需更新框架适配逻辑和测试数据，完成检查及同版本实例冒烟测试后，再更新兼容性记录。`sync` 只修改缓存和锁文件，文档更新与版本发布需单独完成。仅缺少缓存时使用 `prepare`。

-翻译或邮件渲染参考实现哈希变化会阻止同步，须先复核 Go 适配逻辑；下载新版本并不等于确认兼容。官方英文须包含官方模板引用的键，构建另行检查框架键；其它语言缺键回退英文。缓存替换前的网络/校验失败不会修改原输入。缓存替换和根锁文件写入是两个操作：文件系统错误可能留下不一致状态，后续校验会失败，重试前先检查二者。
+已评审的翻译或邮件渲染参考源码发生变化时，须先评审适配逻辑，再更新参考哈希。官方英文必须包含所有引用的翻译键；其他语言缺少的翻译回退为英文。新增邮件类型需要补充框架适配和 `tools/data/templates_config.json` 中的测试数据，该文件提供预览元数据和示例上下文。JSON 测试数据中的整数应保持整数形式，以便 Go 正确格式化。
+
+缓存替换前发生网络或校验错误时，原有文件保持不变。缓存替换和根锁文件写入是两个操作；文件系统错误中断操作后，重试前应检查二者是否一致。

 ### 缓存恢复

-`prepare` 拒绝损坏、不完整或锁文件不匹配的缓存，不合并、不静默修复；`sync` 也拒绝替换非空的无效快照。检查错误后，将精确的生成缓存目录移到备份位置，再按已复核的根锁文件执行 `prepare`。例如在 **仓库根目录的 PowerShell** 中，选择尚不存在的备份名称：
+`prepare` 会报告损坏、不完整或与锁文件不匹配的缓存，不会自动修复。`sync` 同样拒绝替换非空的无效快照。检查错误后，将生成的缓存移至备份位置，再按已评审的根锁文件重新准备。
+
+例如，在**仓库根目录的 PowerShell** 中，使用尚不存在的备份名称：

 ```powershell
 Move-Item -LiteralPath .\build\upstream -Destination .\build\upstream.backup
@@ -82,58 +133,87 @@ go run . upstream prepare
 go run . upstream verify
 ```

-不要删除整个 `build/` 或修改缓存中的官方文件。显式同步后如需回退，恢复之前已复核的根锁文件，再按同样方式重建缓存。避免多个 `sync`/`prepare`/构建进程同时操作同一缓存；替换输入前先停止 `dev`。
+保留 `build/` 中的其他内容，不直接编辑缓存中的官方文件。需要回退快照时，恢复此前已评审的根锁文件，再按同样方式重建缓存。替换输入前先停止 `dev`，避免多个进程同时写入同一缓存。

-邮件类型由快照发现，`tools/data/templates_config.json` 仅提供名称、描述和模拟上下文。新增官方邮件类型后，必须补充测试数据才能通过预览校验。
+### 已知上游格式问题

-Gitea v28.0.0 的波兰语 `mail.team_invite.text_1` 存在已确认的占位符缺陷。预览保留官方行为并报告 `[UPSTREAM-WARN]`，例外严格匹配官方原文。其他格式错误会使渲染失败。不要直接修改语言快照来隐藏官方问题。
-
-## 本地开发
-
-使用 **Go 1.24+**。CLI 依赖 urfave/cli，HTML 校验使用 Go 的 x/net 解析器。先执行 `go mod download` 和 `upstream prepare` 下载依赖及锁定输入，之后可离线构建。
-
-```bash
-cd tools
-go run . list
-go run . build all
-go run . preview all
-go run . dev
-# http://127.0.0.1:3456
-```
-
-`build` 将安装文件写入 `build/themes/<名称>/mail/`。`preview` 同时完成构建，生成小型清单和每种官方语言各自的 JS 数据包。直接打开 `preview/index.html` 即可静态预览，语言加载支持 `file://`。
-
-回环开发服务器监听主题 CSS/元数据、共享框架、锁文件/缓存和测试数据，通过 SSE 刷新。安装模板的 Logo 引用 `{{AppUrl}}assets/img/favicon.png`；仅静态预览的生成数据嵌入下载的官方图标，以支持离线显示。
+Gitea v28.0.0 的波兰语 `mail.team_invite.text_1` 存在占位符缺陷。预览保留官方输出并报告 `[UPSTREAM-WARN]`。该例外仅匹配已评审的完整原文，其他格式错误会使渲染失败。发现上游问题时应报告问题，不修改缓存中的语言文件。

 ## 验证与发布

-测试检查框架适配与生成的确定性、操作锚点变化时失败、官方翻译键及通知语义保留。渲染覆盖全部主题/语言及推送、评审、回复、工作流和附件分支。控件及品牌区域是明确的展示增补；按钮文字、备用链接目标和 Logo 引用单独校验。
+### 拉取请求检查

-发布前，在与快照标签一致的隔离 Gitea 实例中触发真实的密码重置或通知邮件。管理后台的测试邮件按钮不会使用自定义模板。确认模板加载并捕获邮件，避免向真实用户发送测试内容。
+在 `tools/` 中运行 `go test ./...` 和 `go run . preview all`。测试覆盖生成结果的确定性、操作锚点变化、翻译键，以及全部主题和语言的通知主题行、正文与链接。测试数据包含推送、评审、回复、工作流和附件分支；共享控件与品牌展示作为附加内容单独处理。

-可选的 `tools/integration` 测试使用临时 SQLite、用户、Git/SSH 路径及回环 SMTP 自动完成此流程。将 `GITEA_SMOKE_BINARY` 设为已校验官方 SHA-256、版本与快照一致的 Gitea 可执行文件，在 `tools/` 执行 `go test ./integration -v -count=1`。浏览器检查位于 `tools/qa`：生成预览后安装其可选依赖并运行 `npm test`；设置 `PREVIEW_DEV_URL` 可同时检查 HTTP 预览，`--update-gallery` 可更新截图。
+修改文档、追踪脚本或打包流程时，在仓库根目录执行：

-发行标签须与快照中的 Gitea 版本一致，在 `.github/release-notes/vX.Y.Z.md` 添加已复核的说明。工作流校验快照和测试，打包生成主题、多语言预览、文档及官方许可证/来源信息，再更新发布标签区块。源码修改与已发布兼容矩阵保持区分；历史标签和附件不变。
+```bash
+python -B -m unittest discover -s .github/scripts -p 'test_*.py'
+```

-手动打包时，先执行 `preview all`，再从仓库根目录运行 `python .github/scripts/package_release.py --version vX.Y.Z --output <新输出目录>`。发布工作流使用同一脚本；它校验源码/产物哈希和全部语言包，排除未声明的旧构建目录，并拒绝覆盖已有压缩包。
+调整通用说明时，同步更新英文和简体中文指南。拉取请求应说明改动内容及相关检查结果，涉及视觉变化时附上截图。
+
+### 浏览器与 Gitea 实例检查
+
+生成预览数据后，可运行浏览器检查：
+
+```bash
+cd tools/qa
+npm install
+npx playwright install chromium
+npm test
+```
+
+如需使用已安装的 Chrome 或 Edge，设置 `BROWSER_EXECUTABLE_PATH`，无需再安装 Chromium。设置 `PREVIEW_DEV_URL` 可同时检查运行中的 HTTP 预览。`npm test -- --update-gallery` 会一并更新画廊截图。
+
+发布前，在与锁定版本一致的隔离 Gitea 实例中加载生成的模板，捕获真实的密码重置或通知邮件。管理后台的测试邮件按钮不使用自定义模板。
+
+可选的 `tools/integration` 测试使用临时 SQLite 数据、用户、Git/SSH 路径和回环 SMTP。将 `GITEA_SMOKE_BINARY` 设为已校验官方校验值、版本与锁文件一致的 Gitea 可执行文件，再在 `tools/` 中运行 `go test ./integration -v -count=1`。邮件仅在本地捕获，不发送给真实用户。未设置该变量时会跳过此测试。发布工作流不会自动运行可选的浏览器和真实 Gitea 实例检查。
+
+### 准备发行版
+
+发行标签必须与锁定的 Gitea 版本一致。当前源码重构尚未发布，已有 v28.0.0 和历史版本的附件应保留。
+
+1. 完成自动化检查、预览检查和同版本实例冒烟测试。
+2. 在 `.github/release-notes/vX.Y.Z.md` 添加已评审的发行说明，并按验证结果更新兼容性记录。
+3. 在 `tools/` 中运行 `go run . preview all`，生成全部主题和语言数据。
+4. 打包并检查发行包内容后再发布。
+
+手动打包时，在仓库根目录执行：
+
+```bash
+python .github/scripts/package_release.py --version vX.Y.Z --output <new-output-directory>
+```
+
+将版本和输出目录占位符替换为已评审的标签及新的目录。脚本会检查源码与产物哈希，包含所有语言数据包，排除残留的旧主题构建，并拒绝覆盖已有压缩包。
+
+发布工作流使用同一脚本打包模板、预览、文档、官方许可证和来源信息，并更新受管理的版本标记。依赖自动发布前，请确认所用 Gitea 主机的 Actions 支持和写入权限。Markdown 管理区块的说明见[版本追踪](../COMPATIBILITY.md#version-tracking)。
+
+### Gitea 工作流配置
+
+两个工作流均使用 `linux-amd64-docker-small` Runner 标签。任务镜像需要支持检出和工具链安装步骤使用的 Node.js Action，并提供 Git 和 POSIX Shell。Go 与 Python 由安装步骤准备。
+
+PR 创建和发行附件上传通过 `.github/scripts/gitea_actions.py` 调用实例的 `/api/v1` API。工作流传入实例地址、仓库名称和内置 `GITEA_TOKEN`，仓库设置需要允许所请求的代码、发行版及拉取请求写入权限。可选的 `UPSTREAM_GITHUB_TOKEN` Secret 仅用于查询 GitHub 上的官方发行版；未配置时使用 GitHub 的匿名 API 限额。
+
+追踪工作流会复用内容相同的已有分支及对应的未关闭 PR。分支内容不同时需要人工检查，工作流不会强制推送。发布流程拒绝修改任何已有发行版，包括草稿；新版本在两个压缩包上传成功后才从草稿转为发布状态。上传失败时，重试前先检查草稿；已发布版本及附件应保持不变。

 ## 报告问题

-注明快照标签/提交、主题、邮件类型、预览语言和错误。先运行 `go run . upstream verify` 与 `go run . preview all`，附上截图或渲染诊断。
+请提供 Gitea 版本、模板发行版或源码提交、主题、邮件类型、语言和复现步骤。源码构建问题还应包含快照标签与提交，以及 `go run . upstream verify` 或 `go run . preview all` 的输出。显示问题请注明邮件客户端，并附上移除个人信息后的截图。

 ## 提交规范

- `style(<名称>):` — 主题展示样式
- `preview:` — 浏览器预览
- `tools:` — CLI、构建及快照工具
- `docs:` — 文档和翻译
- `fix:` — 修复
- `refactor:` — 重构
- `chore:` — 维护
+| 前缀 | 范围 |
+|---|---|
+| `style(<名称>):` | 主题展示样式 |
+| `preview:` | 浏览器预览 |
+| `tools:` | CLI、构建与快照工具 |
+| `docs:` | 文档和翻译 |
+| `fix:` | 问题修复 |
+| `project:` | 仓库配置和项目结构 |
+| `refactor:` | 代码重构 |
+| `chore:` | 日常维护 |

 ## 翻译与许可证

- [English CONTRIBUTING](../CONTRIBUTING.md)
- 简体中文（本文）
-
-贡献以 MIT 许可证授权，分发派生模板时须保留 Gitea 版权及官方许可证。
+[英文指南](../CONTRIBUTING.md)介绍相同的开发流程。贡献采用 MIT 许可证；分发派生模板时，请保留 Gitea 版权和官方许可证，详见[第三方声明](../THIRD_PARTY_NOTICES.md)。