fix: support Gitea 28.0.0 mail templates

.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)

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

COMPATIBILITY.md

@@ -7,12 +7,13 @@ This document tracks the compatibility between **Gitea Mail Templates** releases
 <!-- TRACKER:QUICK-REF-MAX OFFSET=3 -->
 | 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. <!-- TRACKER:LATEST-VERIFIED -->
+> **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. <!-- TRACKER:LATEST-VERIFIED -->
 
 ## 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
 <!-- TRACKER:VERSION-INSERT OFFSET=2 -->
 | 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
 

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) <!-- TRACKER:BADGE -->
+[![Gitea](https://img.shields.io/badge/Gitea-28.0.0%20%7C%2028.0.0%20tested-blue)](COMPATIBILITY.md) <!-- TRACKER:BADGE -->
 
-> **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)
+- **Gitea 28.0.0** — use template release v28.0.0; earlier Gitea versions require an older package
-- **Latest tested:** Gitea 1.27.3 <!-- TRACKER:LATEST-TESTED -->
+- **Latest tested:** Gitea 28.0.0 <!-- TRACKER:LATEST-TESTED -->
-- **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))
+- **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

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 28.0.0** — 使用模板发布版 v28.0.0；旧版 Gitea 请选用对应的旧版模板
-- **最新测试：** Gitea 1.27.3<!-- TRACKER:LATEST-TESTED -->
+- **最新测试：** Gitea 28.0.0<!-- TRACKER:LATEST-TESTED -->
-- **最新发布版：** [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)）
+- **最新发布版：** [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)
 
 ## 许可证

themes/aurora/mail/repo/release.tmpl

@@ -108,7 +108,7 @@
               {{end}}
               {{if .Release.Attachments}}
                 {{range .Release.Attachments}}
-                  <li><a href="{{.DownloadURL}}">{{.Name}} ({{.Size | FileSize}})</a></li>
+                  <li><a href="{{.DownloadURL}}">{{.Name}} ({{.Size | FormatByteSize}})</a></li>
                 {{end}}
               {{end}}
             </ul>

themes/bloom/mail/repo/release.tmpl

@@ -86,7 +86,7 @@
           {{if .Release.Attachments}}
             {{range .Release.Attachments}}
               <li>
-                <a href="{{.DownloadURL}}" target="_blank" style="color:#3b82f6;text-decoration:none;font-weight:500;">{{.Name}} ({{.Size | FileSize}})</a>
+                <a href="{{.DownloadURL}}" target="_blank" style="color:#3b82f6;text-decoration:none;font-weight:500;">{{.Name}} ({{.Size | FormatByteSize}})</a>
               </li>
             {{end}}
           {{end}}

themes/ember/mail/repo/release.tmpl

@@ -93,7 +93,7 @@
           {{if .Release.Attachments}}
             {{range .Release.Attachments}}
               <li>
-                <a href="{{.DownloadURL}}" target="_blank" style="color:#ea580c;text-decoration:none;font-weight:600;">{{.Name}} ({{.Size | FileSize}})</a>
+                <a href="{{.DownloadURL}}" target="_blank" style="color:#ea580c;text-decoration:none;font-weight:600;">{{.Name}} ({{.Size | FormatByteSize}})</a>
               </li>
             {{end}}
           {{end}}

themes/heritage/mail/repo/release.tmpl

@@ -86,7 +86,7 @@
           {{if .Release.Attachments}}
             {{range .Release.Attachments}}
               <li>
-                <a href="{{.DownloadURL}}" target="_blank" style="color:#1e3a5f;text-decoration:none;font-weight:600;border-bottom:1px dotted #8b6914;">{{.Name}} ({{.Size | FileSize}})</a>
+                <a href="{{.DownloadURL}}" target="_blank" style="color:#1e3a5f;text-decoration:none;font-weight:600;border-bottom:1px dotted #8b6914;">{{.Name}} ({{.Size | FormatByteSize}})</a>
               </li>
             {{end}}
           {{end}}

themes/horizon/mail/repo/release.tmpl

@@ -113,7 +113,7 @@
             {{if .Release.Attachments}}
               {{range .Release.Attachments}}
                 <li>
-                  <a href="{{.DownloadURL}}" target="_blank">{{.Name}} ({{.Size | FileSize}})</a>
+                  <a href="{{.DownloadURL}}" target="_blank">{{.Name}} ({{.Size | FormatByteSize}})</a>
                 </li>
               {{end}}
             {{end}}

themes/ink/mail/repo/release.tmpl

@@ -116,7 +116,7 @@
             {{end}}
             {{if .Release.Attachments}}
               {{range .Release.Attachments}}
-                <li><a href="{{.DownloadURL}}">{{.Name}} ({{.Size | FileSize}})</a></li>
+                <li><a href="{{.DownloadURL}}">{{.Name}} ({{.Size | FormatByteSize}})</a></li>
               {{end}}
             {{end}}
           </ul>

themes/mono/mail/repo/release.tmpl

@@ -99,7 +99,7 @@
                   {{end}}
                   {{if .Release.Attachments}}
                     {{range .Release.Attachments}}
-                      <li><a href="{{.DownloadURL}}">{{.Name}} ({{.Size | FileSize}})</a></li>
+                      <li><a href="{{.DownloadURL}}">{{.Name}} ({{.Size | FormatByteSize}})</a></li>
                     {{end}}
                   {{end}}
                 </ul>

themes/neon/mail/repo/release.tmpl

@@ -101,7 +101,7 @@
               {{end}}
               {{if .Release.Attachments}}
                 {{range .Release.Attachments}}
-                  <li><a href="{{.DownloadURL}}">{{.Name}} ({{.Size | FileSize}})</a></li>
+                  <li><a href="{{.DownloadURL}}">{{.Name}} ({{.Size | FormatByteSize}})</a></li>
                 {{end}}
               {{end}}
             </ul>

themes/terminal/mail/repo/release.tmpl

@@ -99,7 +99,7 @@
               {{end}}
               {{if .Release.Attachments}}
                 {{range .Release.Attachments}}
-                  <li><a href="{{.DownloadURL}}">{{.Name}} ({{.Size | FileSize}})</a></li>
+                  <li><a href="{{.DownloadURL}}">{{.Name}} ({{.Size | FormatByteSize}})</a></li>
                 {{end}}
               {{end}}
             </ul>

themes/terra/mail/repo/release.tmpl

@@ -100,7 +100,7 @@
               {{end}}
               {{if .Release.Attachments}}
                 {{range .Release.Attachments}}
-                  <li><a href="{{.DownloadURL}}">{{.Name}} ({{.Size | FileSize}})</a></li>
+                  <li><a href="{{.DownloadURL}}">{{.Name}} ({{.Size | FormatByteSize}})</a></li>
                 {{end}}
               {{end}}
             </ul>

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
       }

tools/preview/funcs.go

@@ -15,7 +15,7 @@ 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
@@ -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").
+// previewFormatByteSize converts JSON fixture numbers to Gitea's int64 input type.
-func FileSize(n int64) string {
+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.

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")
+			}
+		})
+	}
+}