From 2f27d5425113fcf931dbea35f62feabca66aa8ba Mon Sep 17 00:00:00 2001 From: KenanZhu <3471685733@qq.com> Date: Tue, 23 Jun 2026 10:19:34 +0800 Subject: [PATCH] docs: add Gitea version compatibility matrix and badge - Create COMPATIBILITY.md with version matrix, Gitea release tracking, template variable reference, and compatibility verification process - Add Gitea 1.25+ | 1.26.4 tested badge to README - Update all 6 READMEs (EN + 5 translations) with latest tested version and link to COMPATIBILITY.md - Include COMPATIBILITY.md in release artifacts Co-Authored-By: Claude --- .github/workflows/release.yml | 2 +- COMPATIBILITY.md | 92 +++++++++++++++++++++++++++++++++++ README.md | 10 ++-- docs/README.ja.md | 4 +- docs/README.ko.md | 9 ++++ docs/README.ru.md | 4 +- docs/README.zh-CN.md | 4 +- docs/README.zh-TW.md | 4 +- 8 files changed, 120 insertions(+), 9 deletions(-) create mode 100644 COMPATIBILITY.md diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index aa67cde..35e22ca 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -33,7 +33,7 @@ jobs: VERSION=${GITHUB_REF#refs/tags/} ARCHIVE="gitea-mail-templates-${VERSION}" mkdir -p dist - cp -r themes LICENSE README.md "dist/${ARCHIVE}" + cp -r themes LICENSE README.md COMPATIBILITY.md "dist/${ARCHIVE}" cd dist zip -r "${ARCHIVE}.zip" "${ARCHIVE}" tar -czf "${ARCHIVE}.tar.gz" "${ARCHIVE}" diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md new file mode 100644 index 0000000..b1a3a82 --- /dev/null +++ b/COMPATIBILITY.md @@ -0,0 +1,92 @@ +# Gitea Compatibility + +This document tracks the compatibility between **Gitea Mail Templates** releases and **Gitea** versions. + +## Quick Reference + +| Template Release | Min Gitea | Max Tested Gitea | Status | +|-----------------|-----------|-----------------|--------| +| **v1.0.x** | **1.25.0** | **1.26.4** | ✅ Active | + +> **Latest verified:** All 11 templates pass validation against Gitea 1.26.4 data contexts. + +## Check Your Gitea Version + +```bash +# On your Gitea server: +gitea --version +# Or check the web UI footer / Site Administration → Monitoring +``` + +## Gitea Version History — Mail Template Impact + +| Gitea | Release Date | Mail Template Changes | Breaking? | +|-------|-------------|----------------------|-----------| +| **1.26.4** | 2026-06-21 | None — hotfix release | No | +| **1.26.3** | 2026-06-20 | None — security release | No | +| **1.26.2** | 2026-05-20 | None — security + bug fixes | No | +| **1.26.1** | 2026-04-22 | None — bug fixes | No | +| **1.26.0** | 2026-04-19 | AppURL cleanup; SanitizeHTML deprecated → use HTMLFormat | No | +| **1.25.5** | 2026-03-10 | None — security + maintenance | No | +| **1.25.0** | 2025 | **Directory restructure** — templates moved to `mail//.tmpl` (PR #35150); subject/body split with `---` separator; template preview support added | **Yes** (structural) | +| **≤ 1.24.x** | — | Flat directory structure under `custom/templates/mail/` | ❌ Unsupported | + +## Template Variable Reference + +All 11 template types use only Gitea built-in variables and functions. Verified against Gitea source (`services/mailer/` + `modules/templates/mail.go`). + +### Template Functions (available in all templates) + +| Function | Since Gitea | Notes | +|----------|------------|-------| +| `AppName` | ≤ 1.21 | Application name | +| `AppUrl` | ≤ 1.21 | Application base URL | +| `AppDomain` | ≤ 1.21 | Server domain | +| `DotEscape` | ≤ 1.21 | Prevents auto-linking of dotted text | +| `QueryEscape` | ≤ 1.21 | URL query encoding | +| `PathEscapeSegments` | ≤ 1.21 | Per-segment path encoding | +| `ShortSha` | ≤ 1.21 | Truncated commit hash | +| `FileSize` | ≤ 1.21 | Human-readable file size | +| `HTMLFormat` | ≤ 1.21 | Render string as safe HTML | +| `Iif` | ≤ 1.21 | Inline conditional | +| `dict` | ≤ 1.21 | Build maps from key-value pairs | +| `Eval` | ≤ 1.21 | Evaluate template tokens | +| `StringUtils` | ≤ 1.21 | String manipulation helpers | +| `SliceUtils` | ≤ 1.21 | Slice manipulation helpers | +| `JsonUtils` | ≤ 1.21 | JSON helpers | +| `DumpVar` | ≤ 1.21 | Debug variable dump | +| `SanitizeHTML` | ≤ 1.21 | **Deprecated in 1.26** — use `HTMLFormat` | + +### Data Contexts by Template + +| Template | Key Variables | +|----------|--------------| +| `user/auth/activate` | `DisplayName`, `Code`, `ActiveCodeLives` | +| `user/auth/activate_email` | `DisplayName`, `Code`, `Email`, `ActiveCodeLives` | +| `user/auth/register_notify` | `DisplayName`, `Username` | +| `user/auth/reset_passwd` | `DisplayName`, `Code`, `ResetPwdCodeLives` | +| `org/team_invite` | `Inviter`, `Team`, `Organization`, `InviteURL`, `Invite` | +| `repo/collaborator` | `Subject`, `RepoName`, `Link` | +| `repo/transfer` | `Doer`, `User`, `Repo`, `Link`, `Destination` | +| `repo/release` | `Release` (with `Publisher`, `TagName`, `Title`, `RenderedNote`, `Attachments`), `Link` | +| `repo/actions/workflow_run` | `Run` (with `WorkflowID`, `HTMLURL`), `Jobs`, `RunStatusText` | +| `repo/issue/assigned` | `Doer`, `Issue`, `Link`, `IsPull` | +| `repo/issue/default` | `Doer`, `Issue`, `Link`, `Body`, `ActionName`, `Comment`, `IsPull`, `IsMention`, `ReviewComments`, `CanReply` | + +> ⚠️ **`.DisplayName`** is not available in collaborator, transfer, release, workflow_run, assigned, and default templates — do not reference it. + +### Translation Keys + +All templates use Gitea's official `mail.*` translation namespace. Keys are stable across Gitea 1.25+. + +## How Compatibility Is Verified + +1. **Automated lint** — CI renders all templates via `go run . preview all` on every push +2. **Source audit** — Template data contexts are cross-referenced against Gitea's `services/mailer/` package +3. **Release checklist** — Each release confirms the max-tested Gitea version in this file + +## Reporting Issues + +If you find a compatibility problem with a specific Gitea version: +1. Check the [Gitea changelog](https://github.com/go-gitea/gitea/blob/main/CHANGELOG.md) for recent mail template changes +2. Open an issue with: your Gitea version, which template, and the error diff --git a/README.md b/README.md index fdbb069..4e0e319 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ A curated collection of professionally designed, audience-driven email templates for self-hosted [Gitea](https://about.gitea.com) instances. +[![Gitea](https://img.shields.io/badge/Gitea-1.25+%20%7C%201.26.4%20tested-blue)](COMPATIBILITY.md) + > **110 template files — 10 visual styles, 11 email types each** --- @@ -161,10 +163,10 @@ gitea-mail-templates/ ## Compatibility -- **Gitea 1.25+** — matches the refactored mail template directory structure introduced in v1.25 -- 100% variable-compatible with official Gitea templates -- Uses only built-in Gitea template functions -- Uses only official Gitea translation keys +- **Gitea 1.25+** — matches the refactored mail template directory structure (v1.25) +- **Latest tested:** Gitea 1.26.4 +- 100% variable-compatible with official Gitea templates — see [COMPATIBILITY.md](COMPATIBILITY.md) for the full matrix +- Uses only built-in Gitea template functions and official translation keys - No custom template functions or locale patches required --- diff --git a/docs/README.ja.md b/docs/README.ja.md index 96d5b05..54143c4 100644 --- a/docs/README.ja.md +++ b/docs/README.ja.md @@ -57,7 +57,9 @@ cd tools && go run . dev ## 互換性 -- **Gitea 1.25+**, 100%互換, 組み込み関数のみ +- **Gitea 1.25+** — v1.25で導入されたメールテンプレートディレクトリ構造 +- **最新テスト:** Gitea 1.26.4 +- Gitea公式テンプレートと100%互換 — 詳細は [COMPATIBILITY.md](COMPATIBILITY.md)を参照 ## ライセンス diff --git a/docs/README.ko.md b/docs/README.ko.md index 67e1774..53d341a 100644 --- a/docs/README.ko.md +++ b/docs/README.ko.md @@ -55,3 +55,12 @@ cd tools && go run . dev # → http://localhost:3456 ``` +## 호환성 + +- **Gitea 1.25+** — v1.25에서 도입된 메일 템플릿 디렉토리 구조 사용 +- **최신 테스트:** Gitea 1.26.4 +- Gitea 공식 템플릿과 100% 호환 — 자세한 내용은 [COMPATIBILITY.md](../COMPATIBILITY.md) 참조 + +## 라이선스 + +MIT — [LICENSE](../LICENSE). diff --git a/docs/README.ru.md b/docs/README.ru.md index 4a8efc4..f524811 100644 --- a/docs/README.ru.md +++ b/docs/README.ru.md @@ -57,7 +57,9 @@ cd tools && go run . dev ## Совместимость -- **Gitea 1.25+**, 100% совместимость, только встроенные функции +- **Gitea 1.25+** — структура директорий из v1.25 +- **Последняя проверка:** Gitea 1.26.4 +- 100% совместимость с официальными шаблонами Gitea — см. [COMPATIBILITY.md](COMPATIBILITY.md) ## Лицензия diff --git a/docs/README.zh-CN.md b/docs/README.zh-CN.md index 118cdea..25fb1d7 100644 --- a/docs/README.zh-CN.md +++ b/docs/README.zh-CN.md @@ -78,7 +78,9 @@ cd tools && go run . dev ## 兼容性 -- **Gitea 1.25+**，100% 变量兼容，仅使用内置函数和官方翻译键 +- **Gitea 1.25+** — v1.25 引入的邮件模板目录结构 +- **最新测试：** Gitea 1.26.4 +- 与 Gitea 官方模板 100% 兼容 — 详见 [COMPATIBILITY.md](COMPATIBILITY.md) ## 许可证 diff --git a/docs/README.zh-TW.md b/docs/README.zh-TW.md index 38c5bfa..2ae19b4 100644 --- a/docs/README.zh-TW.md +++ b/docs/README.zh-TW.md @@ -73,7 +73,9 @@ cd tools && go run . dev ## 相容性 -- **Gitea 1.25+**，100% 變數相容，僅使用內建函式和官方翻譯鍵 +- **Gitea 1.25+** — v1.25 引入的郵件模板目錄結構 +- **最新測試：** Gitea 1.26.4 +- 與 Gitea 官方模板 100% 相容 — 詳見 [COMPATIBILITY.md](COMPATIBILITY.md) ## 授權