diff --git a/.github/release-notes/v28.0.0.md b/.github/release-notes/v28.0.0.md new file mode 100644 index 0000000..6d6daea --- /dev/null +++ b/.github/release-notes/v28.0.0.md @@ -0,0 +1,21 @@ +FEATURES + +- COMPATIBILITY + - Add a Gitea 28.0.0-aligned release of all 10 themes and 11 mail types per theme + +BUGFIXES + +- THEMES (All 10) + - Replace the removed `FileSize` function with `FormatByteSize` in release-attachment emails, preventing Gitea 28.0.0 template rendering errors +- PREVIEW AND TESTS + - Match the preview's file-size function to Gitea 28.0.0 and render release attachments in the example data + - Add an all-theme regression test for release attachments and the removed function + +DOCS + +- Update the English and Simplified Chinese READMEs and compatibility matrix for Gitea 28.0.0 +- Clarify that v28.0.0 requires Gitea 28.0.0; use v1.27.3 for Gitea 1.25.0–1.27.3 + +--- + +**Full Changelog:** [v1.27.3...v28.0.0](https://github.com/KenanZhu/GiteaMailTemplates/compare/v1.27.3...v28.0.0) diff --git a/AGENTS.md b/AGENTS.md index 5f4d400..9d7eb11 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,7 +35,7 @@ docs/ # Bilingual documentation (English + Simplified Chinese) ### Template Files - All `.tmpl` files use Go `html/template` syntax -- Must use only Gitea's built-in template functions: `AppUrl`, `DotEscape`, `QueryEscape`, `ShortSha`, `HTMLFormat`, `PathEscapeSegments`, `FileSize` +- Must use only Gitea 28's built-in template functions: `AppUrl`, `DotEscape`, `QueryEscape`, `ShortSha`, `HTMLFormat`, `PathEscapeSegments`, `FormatByteSize` - Must use only official Gitea translation keys (`mail.*` namespace) - Never reference `.DisplayName` in templates where the data context lacks it (collaborator, transfer, release, workflow_run, assigned, default) - Each style must have all 11 template types @@ -67,7 +67,7 @@ docs/ # Bilingual documentation (English + Simplified Chinese) ## Versioning - Release tags identify actual downloadable packages; the compatibility matrix distinguishes released tags from source-only fixes -- The current release is **v1.27.3**, verified against Gitea 1.27.3; it fixes the push-notification bug in Bloom, Ember, and Heritage that affects v1.27.2 on Gitea 1.27.1+. The quick-reference table in `COMPATIBILITY.md` lists the active release first; the tracker workflow updates that row by position +- The current release is **v28.0.0**, verified against Gitea 28.0.0. Gitea 28 removes `FileSize` in favor of `FormatByteSize`, so v28.0.0 is not compatible with Gitea 1.25.0–1.27.3; use v1.27.3 for those versions. The quick-reference table in `COMPATIBILITY.md` lists the active release first; the tracker workflow updates that row by position - When a new Gitea version is checked: update the top `COMPATIBILITY.md` row and README badge; keep unreleased fixes distinct from the published release, and update verified/tested wording only after verification - Tag a new release (`vX.Y.Z`) only when the template content itself changes — the release workflow packages automatically on tag push - Before tagging, add `.github/release-notes/vX.Y.Z.md`; the release workflow validates the file, runs `go test ./...`, and publishes those reviewed notes with the archives diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md index c06c134..c339774 100644 --- a/COMPATIBILITY.md +++ b/COMPATIBILITY.md @@ -7,12 +7,13 @@ This document tracks the compatibility between **Gitea Mail Templates** releases | Template Release | Min Gitea | Max Tested Gitea | Status | |-----------------|-----------|-----------------|--------| -| **v1.27.3** | **1.25.0** | **1.27.3** | ✅ Active | +| **v28.0.0** | **28.0.0** | **28.0.0** | ✅ Active | +| **v1.27.3** | **1.25.0** | **1.27.3** | ✅ Superseded; release emails fail on Gitea 28.0.0 (`FileSize` removed) | | **v1.27.2** | **1.25.0** | **1.27.3** | ⚠️ Push notices fail in Bloom, Ember, and Heritage on Gitea 1.27.1+ | | **v1.0.1** | **1.25.0** | **1.27.0** | ✅ Superseded; push notices need newer release on 1.27.1+ | | **v1.0.0** | **1.25.0** | **1.26.4** | ✅ Superseded | -> **Latest verified:** Release v1.27.3 passes the Gitea 1.27.3 source audit and push-render test. The older v1.27.2 archive contains three broken push-notification templates. +> **Latest verified:** Release v28.0.0 passes the Gitea 28.0.0 mail-template, mailer-context, function, and translation-key source audit plus all-theme rendering tests. This release requires Gitea 28.0.0; use v1.27.3 for Gitea 1.25.0–1.27.3. ## Versioning @@ -20,6 +21,7 @@ The release tag identifies the downloadable template package. The supported Gite | Gitea version | Template release | |---------------|------------------| +| 28.0.0 | **v28.0.0**; older releases use the removed `FileSize` function in release emails | | 1.27.3 | **v1.27.3**; v1.27.2 has a push-notification issue in three themes | | 1.27.2 | **v1.27.3**; v1.27.2 has the same issue | | 1.27.1 | **v1.27.3**; v1.27.2 has the same issue | @@ -27,6 +29,7 @@ The release tag identifies the downloadable template package. The supported Gite - The [tracker workflow](.github/workflows/gitea-tracker.yml) opens a PR when a new Gitea release appears, marking it ⏳ Pending Verification. - After verification, update the top **Template Release** row. Keep fixes on `main` marked **unreleased** until a new tag is published; the [release workflow](.github/workflows/release.yml) packages the archive on tag push. - The older `v1.0.1` tag predates the Gitea 1.27.1 push notification data fix and should not be used for Gitea 1.27.1 or newer. +- Gitea 28.0.0 replaces the mail-template `FileSize` function with `FormatByteSize`. The two functions are not interchangeable across these Gitea versions; use the matching template release. ## Check Your Gitea Version @@ -41,6 +44,7 @@ gitea --version | Gitea | Release Date | Mail Template Changes | Breaking? | |-------|-------------|----------------------|-----------| +| **28.0.0** | 2026-09-29 | `FileSize` removed and `FormatByteSize` added; mail templates now have `mail/`-prefixed internal names and shared head/footer partials; workflow emails gain status-icon fields. Our custom template paths and referenced data fields remain valid. | **Yes** (release attachment formatting) | | **1.27.3** | 2026-08-29 | No upstream mail template, mailer, or locale changes; an existing push-notification defect in three themes is fixed in template release v1.27.3 | No upstream break | | **1.27.2** | 2026-08-14 | None — security + bug fixes | No | | **1.27.1** | 2026-07-27 | Push commit data paths changed: .ID → .UserCommit.GitCommit.ID (#38467); older custom templates can fail on push notifications | Yes (old .ID paths) | @@ -69,7 +73,7 @@ All 11 template types use only Gitea built-in variables and functions. Verified | `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 | +| `FormatByteSize` | 28.0.0 | Human-readable IEC file size; replaces `FileSize` | | `HTMLFormat` | ≤ 1.21 | Render string as safe HTML | | `Iif` | ≤ 1.21 | Inline conditional | | `dict` | ≤ 1.21 | Build maps from key-value pairs | @@ -100,13 +104,14 @@ All 11 template types use only Gitea built-in variables and functions. Verified ### Translation Keys -All templates use Gitea's official `mail.*` translation namespace. Keys are stable across Gitea 1.25+. +All templates use Gitea's official `mail.*` translation namespace. Every referenced key was checked against Gitea 28.0.0's English locale file. ## How Compatibility Is Verified -1. **Automated lint** — CI renders all templates via `go run . preview all` on every push +1. **Automated lint** — CI renders all templates via `go run . preview all` on every push; the preview function map mirrors Gitea 28.0.0 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 +3. **Regression tests** — Go tests render push notifications and release attachments in all 10 themes +4. **Release checklist** — Each release confirms the max-tested Gitea version in this file ## Automated Tracking diff --git a/README.md b/README.md index b4dafe1..2a53eeb 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ 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.27.3%20tested-blue)](COMPATIBILITY.md) +[![Gitea](https://img.shields.io/badge/Gitea-28.0.0%20%7C%2028.0.0%20tested-blue)](COMPATIBILITY.md) -> **Release v1.27.3 — verified with Gitea 1.27.3 — 110 template files, 10 visual styles, 11 email types each.** +> **Release v28.0.0 — verified with Gitea 28.0.0 — 110 template files, 10 visual styles, 11 email types each.** --- @@ -163,9 +163,9 @@ gitea-mail-templates/ ## Compatibility -- **Gitea 1.25+** — matches the refactored mail template directory structure (v1.25) -- **Latest tested:** Gitea 1.27.3 -- **Latest release:** [v1.27.3](https://github.com/KenanZhu/GiteaMailTemplates/releases/tag/v1.27.3) fixes push notifications in Bloom, Ember, and Heritage on Gitea 1.27.1+. The older v1.27.2 archive is affected (see [COMPATIBILITY.md](COMPATIBILITY.md)) +- **Gitea 28.0.0** — use template release v28.0.0; earlier Gitea versions require an older package +- **Latest tested:** Gitea 28.0.0 +- **Latest release:** [v28.0.0](https://github.com/KenanZhu/GiteaMailTemplates/releases/tag/v28.0.0) updates all 10 release-notification templates for Gitea's `FormatByteSize` function. Use [v1.27.3](https://github.com/KenanZhu/GiteaMailTemplates/releases/tag/v1.27.3) for Gitea 1.25.0–1.27.3 (see [COMPATIBILITY.md](COMPATIBILITY.md)) - The current source uses Gitea's official template data paths — see [COMPATIBILITY.md](COMPATIBILITY.md) for release-specific limitations - Uses only built-in Gitea template functions and official translation keys - No custom template functions or locale patches required diff --git a/docs/README.zh-CN.md b/docs/README.zh-CN.md index 9939eda..5ffb5a1 100644 --- a/docs/README.zh-CN.md +++ b/docs/README.zh-CN.md @@ -2,7 +2,7 @@ 为自托管 [Gitea](https://about.gitea.com) 实例精心设计、面向不同受众的邮件模板集合。 -> **发布版 v1.27.3 — 已通过 Gitea 1.27.3 兼容性检查 — 110 个模板文件、10 种视觉风格、每种 11 种邮件类型** +> **发布版 v28.0.0 — 已通过 Gitea 28.0.0 兼容性检查 — 110 个模板文件、10 种视觉风格、每种 11 种邮件类型** --- @@ -78,9 +78,9 @@ cd tools && go run . dev ## 兼容性 -- **Gitea 1.25+** — v1.25 引入的邮件模板目录结构 -- **最新测试：** Gitea 1.27.3 -- **最新发布版：** [v1.27.3](https://github.com/KenanZhu/GiteaMailTemplates/releases/tag/v1.27.3) 已修复 Bloom、Ember、Heritage 主题在 Gitea 1.27.1+ 上的推送通知问题；旧版 v1.27.2 压缩包仍受影响（详见 [兼容性说明](../COMPATIBILITY.md)） +- **Gitea 28.0.0** — 使用模板发布版 v28.0.0；旧版 Gitea 请选用对应的旧版模板 +- **最新测试：** Gitea 28.0.0 +- **最新发布版：** [v28.0.0](https://github.com/KenanZhu/GiteaMailTemplates/releases/tag/v28.0.0) 已将全部 10 个主题的发布通知适配为 `FormatByteSize`；Gitea 1.25.0–1.27.3 请使用 [v1.27.3](https://github.com/KenanZhu/GiteaMailTemplates/releases/tag/v1.27.3)（详见[兼容性说明](../COMPATIBILITY.md)） - 当前源码使用 Gitea 官方模板的数据路径；各发布版的限制详见 [兼容性说明](../COMPATIBILITY.md) ## 许可证 diff --git a/themes/aurora/mail/repo/release.tmpl b/themes/aurora/mail/repo/release.tmpl index 39a9bd3..cb88dda 100644 --- a/themes/aurora/mail/repo/release.tmpl +++ b/themes/aurora/mail/repo/release.tmpl @@ -108,7 +108,7 @@ {{end}} {{if .Release.Attachments}} {{range .Release.Attachments}} -
  • {{.Name}} ({{.Size | FileSize}})
    • +
  • {{.Name}} ({{.Size | FormatByteSize}})
    • {{end}} {{end}} diff --git a/themes/bloom/mail/repo/release.tmpl b/themes/bloom/mail/repo/release.tmpl index 599cc24..acd51d4 100644 --- a/themes/bloom/mail/repo/release.tmpl +++ b/themes/bloom/mail/repo/release.tmpl @@ -86,7 +86,7 @@ {{if .Release.Attachments}} {{range .Release.Attachments}}
  • - {{.Name}} ({{.Size | FileSize}}) + {{.Name}} ({{.Size | FormatByteSize}})
    • {{end}} {{end}} @@ -119,4 +119,4 @@ - \ No newline at end of file + diff --git a/themes/ember/mail/repo/release.tmpl b/themes/ember/mail/repo/release.tmpl index 8822b1d..103f1d5 100644 --- a/themes/ember/mail/repo/release.tmpl +++ b/themes/ember/mail/repo/release.tmpl @@ -93,7 +93,7 @@ {{if .Release.Attachments}} {{range .Release.Attachments}}
  • - {{.Name}} ({{.Size | FileSize}}) + {{.Name}} ({{.Size | FormatByteSize}})
    • {{end}} {{end}} @@ -126,4 +126,4 @@ - \ No newline at end of file + diff --git a/themes/heritage/mail/repo/release.tmpl b/themes/heritage/mail/repo/release.tmpl index edfd891..283d327 100644 --- a/themes/heritage/mail/repo/release.tmpl +++ b/themes/heritage/mail/repo/release.tmpl @@ -86,7 +86,7 @@ {{if .Release.Attachments}} {{range .Release.Attachments}}
  • - {{.Name}} ({{.Size | FileSize}}) + {{.Name}} ({{.Size | FormatByteSize}})
    • {{end}} {{end}} @@ -119,4 +119,4 @@ - \ No newline at end of file + diff --git a/themes/horizon/mail/repo/release.tmpl b/themes/horizon/mail/repo/release.tmpl index 1276f44..a3ae144 100644 --- a/themes/horizon/mail/repo/release.tmpl +++ b/themes/horizon/mail/repo/release.tmpl @@ -113,7 +113,7 @@ {{if .Release.Attachments}} {{range .Release.Attachments}}
  • - {{.Name}} ({{.Size | FileSize}}) + {{.Name}} ({{.Size | FormatByteSize}})
    • {{end}} {{end}} @@ -166,4 +166,4 @@ - \ No newline at end of file + diff --git a/themes/ink/mail/repo/release.tmpl b/themes/ink/mail/repo/release.tmpl index 302170f..215c829 100644 --- a/themes/ink/mail/repo/release.tmpl +++ b/themes/ink/mail/repo/release.tmpl @@ -116,7 +116,7 @@ {{end}} {{if .Release.Attachments}} {{range .Release.Attachments}} -
  • {{.Name}} ({{.Size | FileSize}})
    • +
  • {{.Name}} ({{.Size | FormatByteSize}})
    • {{end}} {{end}} @@ -167,4 +167,4 @@ - \ No newline at end of file + diff --git a/themes/mono/mail/repo/release.tmpl b/themes/mono/mail/repo/release.tmpl index 6dbff87..a0b9d71 100644 --- a/themes/mono/mail/repo/release.tmpl +++ b/themes/mono/mail/repo/release.tmpl @@ -99,7 +99,7 @@ {{end}} {{if .Release.Attachments}} {{range .Release.Attachments}} -
  • {{.Name}} ({{.Size | FileSize}})
    • +
  • {{.Name}} ({{.Size | FormatByteSize}})
    • {{end}} {{end}} @@ -149,4 +149,4 @@ - \ No newline at end of file + diff --git a/themes/neon/mail/repo/release.tmpl b/themes/neon/mail/repo/release.tmpl index 42dd249..6c4e0d0 100644 --- a/themes/neon/mail/repo/release.tmpl +++ b/themes/neon/mail/repo/release.tmpl @@ -101,7 +101,7 @@ {{end}} {{if .Release.Attachments}} {{range .Release.Attachments}} -
  • {{.Name}} ({{.Size | FileSize}})
    • +
  • {{.Name}} ({{.Size | FormatByteSize}})
    • {{end}} {{end}} @@ -156,4 +156,4 @@ - \ No newline at end of file + diff --git a/themes/terminal/mail/repo/release.tmpl b/themes/terminal/mail/repo/release.tmpl index 376cfdb..b91c8fe 100644 --- a/themes/terminal/mail/repo/release.tmpl +++ b/themes/terminal/mail/repo/release.tmpl @@ -99,7 +99,7 @@ {{end}} {{if .Release.Attachments}} {{range .Release.Attachments}} -
  • {{.Name}} ({{.Size | FileSize}})
    • +
  • {{.Name}} ({{.Size | FormatByteSize}})
    • {{end}} {{end}} @@ -162,4 +162,4 @@ - \ No newline at end of file + diff --git a/themes/terra/mail/repo/release.tmpl b/themes/terra/mail/repo/release.tmpl index 20aeccf..a50ea5b 100644 --- a/themes/terra/mail/repo/release.tmpl +++ b/themes/terra/mail/repo/release.tmpl @@ -100,7 +100,7 @@ {{end}} {{if .Release.Attachments}} {{range .Release.Attachments}} -
  • {{.Name}} ({{.Size | FileSize}})
    • +
  • {{.Name}} ({{.Size | FormatByteSize}})
    • {{end}} {{end}} @@ -155,4 +155,4 @@ - \ No newline at end of file + diff --git a/tools/data/templates_config.json b/tools/data/templates_config.json index 8e10a3f..75574f3 100644 --- a/tools/data/templates_config.json +++ b/tools/data/templates_config.json @@ -89,7 +89,9 @@ "HTMLURL": "https://gitea.example.com/repo/project", "FullName": "acme/project" }, - "Attachments": [] + "Attachments": [ + { "Name": "release-notes.txt", "DownloadURL": "https://gitea.example.com/repo/project/releases/download/v2.0.0/release-notes.txt", "Size": 1536 } + ] }, "DisableDownloadSourceArchives": false } diff --git a/tools/preview/funcs.go b/tools/preview/funcs.go index ba62607..ed0b34d 100644 --- a/tools/preview/funcs.go +++ b/tools/preview/funcs.go @@ -15,10 +15,10 @@ var TemplateFuncs = template.FuncMap{ "QueryEscape": url.QueryEscape, "ShortSha": ShortSha, "PathEscapeSegments": PathEscapeSegments, - "FileSize": FileSize, + "FormatByteSize": previewFormatByteSize, "HTMLFormat": HTMLFormat, "Dict": Dict, - "gt": Gt, // override built-in for JSON float64/int coercion + "gt": Gt, // override built-in for JSON float64/int coercion "lt": Lt, "ge": Ge, "le": Le, @@ -41,8 +41,20 @@ func PathEscapeSegments(s string) string { return strings.Join(parts, "/") } -// FileSize formats a byte count as a human-readable string (e.g. "2.5 MB"). -func FileSize(n int64) string { +// previewFormatByteSize converts JSON fixture numbers to Gitea's int64 input type. +func previewFormatByteSize(size any) (string, error) { + switch n := size.(type) { + case int64: + return FormatByteSize(n), nil + case float64: + return FormatByteSize(int64(n)), nil + default: + return "", fmt.Errorf("FormatByteSize: unsupported size type %T", size) + } +} + +// FormatByteSize mirrors Gitea 28's IEC attachment size formatting. +func FormatByteSize(n int64) string { const unit = 1024 if n < unit { return fmt.Sprintf("%d B", n) @@ -52,7 +64,7 @@ func FileSize(n int64) string { div *= unit exp++ } - return fmt.Sprintf("%.1f %s", float64(n)/float64(div), []string{"KB", "MB", "GB", "TB"}[exp]) + return fmt.Sprintf("%.1f %s", float64(n)/float64(div), []string{"KiB", "MiB", "GiB", "TiB"}[exp]) } // HTMLFormat substitutes %s/%d placeholders with HTML-escaped values. diff --git a/tools/preview/release_test.go b/tools/preview/release_test.go new file mode 100644 index 0000000..1d81829 --- /dev/null +++ b/tools/preview/release_test.go @@ -0,0 +1,53 @@ +package preview + +import ( + "html/template" + "os" + "path/filepath" + "strings" + "testing" + + "gitea-mail-templates/tools/config" +) + +// Gitea 28 removes FileSize, so render an attachment in every release theme. +func TestReleaseAttachmentsGitea28(t *testing.T) { + if _, ok := TemplateFuncs["FileSize"]; ok { + t.Fatal("FileSize is not available in Gitea 28 mail templates") + } + cfg, err := config.Load(filepath.Join("..", "data", "templates_config.json")) + if err != nil { + t.Fatal(err) + } + data := cfg.Templates["release"].Params + data["locale"] = Locale{} + markSafeHTML(data) + + themesDir := filepath.Join("..", "..", "themes") + themes, err := os.ReadDir(themesDir) + if err != nil { + t.Fatal(err) + } + for _, theme := range themes { + if !theme.IsDir() { + continue + } + t.Run(theme.Name(), func(t *testing.T) { + content, err := os.ReadFile(filepath.Join(themesDir, theme.Name(), "mail", "repo", "release.tmpl")) + if err != nil { + t.Fatal(err) + } + tmpl, err := template.New("release").Funcs(TemplateFuncs).Parse(string(content)) + if err != nil { + t.Fatal(err) + } + var rendered strings.Builder + if err := tmpl.Execute(&rendered, data); err != nil { + t.Fatal(err) + } + if !strings.Contains(rendered.String(), "release-notes.txt") || !strings.Contains(rendered.String(), "1.5 KiB") { + t.Fatal("release attachment or formatted size missing from email") + } + }) + } +}