KenanZhu/GiteaMailTemplates
1
1 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity

docs: clarify per-version Gitea compatibility
Release / Validate Templates (push) Canceled after 0s
Details
Release / Package & Release (push) Canceled after 0s
Details
Release / Update Latest Release Documentation (push) Canceled after 0s
Details

Browse Source
This commit is contained in:
KenanZhu committed 2026-10-09 12:27:00 +08:00
1 parent 14dc37046d
commit 5c0589f6f6
7 files changed
+90 -77
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.github/scripts/test_track_gitea_release.py
+16 -13
View File
@@ -17,22 +17,19 @@ RELEASE_URL = "https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/l
FIXTURES = { FIXTURES = {
"COMPATIBILITY.md": """# Gitea Compatibility "COMPATIBILITY.md": """# Gitea Compatibility
<!-- DOC-TAGS: {"TRACKER":["LATEST-VERIFIED","VERSION-MAP","HISTORY"]} --> <!-- DOC-TAGS: {"TRACKER":["LATEST-VERIFIED","VERSION-MAP","HISTORY"]} -->
| Template Release | Min Gitea | Max Tested Gitea | Status |
|---|---|---|---|
| **v28.0.0** | **28.0.0** | **28.0.0** | [PASS] Active |
<!-- TRACKER:LATEST-VERIFIED --> <!-- TRACKER:LATEST-VERIFIED -->
> **Latest verified:** Release v28.0.0 passes tests. > **Latest verified:** Release v28.0.0 passes tests.
<!-- /TRACKER:LATEST-VERIFIED --> <!-- /TRACKER:LATEST-VERIFIED -->
<!-- TRACKER:VERSION-MAP --> <!-- TRACKER:VERSION-MAP -->
| Gitea version | Template release | | Gitea version | Recommended template release | Status | Notes |
|---|---| |---|---|---|---|
| 28.1.0 | [PENDING] Compatibility verification; no tested template release yet | | 28.1.0 | — | [PENDING] | Compatibility verification pending |
| 28.0.0 | **v28.0.0** | | 28.0.0 | **v28.0.0** | [PASS] | Tested |
<!-- /TRACKER:VERSION-MAP --> <!-- /TRACKER:VERSION-MAP -->
<!-- TRACKER:HISTORY --> <!-- TRACKER:HISTORY -->
| Gitea | Release Date | Mail Template Changes | Breaking? | | Gitea | Release Date | Mail Template Changes | Impact |
|---|---|---|---| |---|---|---|---|
| **28.1.0** | 2026-10-06 | [PENDING] Mail-template compatibility verification | TBD | | **28.1.0** | 2026-10-06 | [PENDING] Review of mail-template changes | TBD |
| **28.0.0** | 2026-09-29 | FormatByteSize | Yes | | **28.0.0** | 2026-09-29 | FormatByteSize | Yes |
| **≤ 1.24.x** | — | Old directory | [UNSUPPORTED] | | **≤ 1.24.x** | — | Old directory | [UNSUPPORTED] |
<!-- /TRACKER:HISTORY --> <!-- /TRACKER:HISTORY -->
@@ -107,9 +104,9 @@ class TrackerTests(unittest.TestCase):
changed = TRACKER.apply_release(self.root, "28.2.0", "2026-11-01") changed = TRACKER.apply_release(self.root, "28.2.0", "2026-11-01")
self.assertEqual({self.root / name for name in self.paths}, set(changed)) self.assertEqual({self.root / name for name in self.paths}, set(changed))
compatibility = self.read("COMPATIBILITY.md") compatibility = self.read("COMPATIBILITY.md")
self.assertIn("| 28.2.0 | [PENDING] Compatibility verification", compatibility) self.assertIn("| 28.2.0 | — | [PENDING] | Compatibility verification pending |", compatibility)
self.assertIn("| **28.2.0** | 2026-11-01 | [PENDING]", compatibility) self.assertIn("| **28.2.0** | 2026-11-01 | [PENDING]", compatibility)
self.assertIn("| **v28.0.0** | **28.0.0** | **28.0.0** | [PASS] Active |", compatibility) self.assertIn("| 28.0.0 | **v28.0.0** | [PASS] | Tested |", compatibility)
self.assertIn("Latest verified:** Release v28.0.0", compatibility) self.assertIn("Latest verified:** Release v28.0.0", compatibility)
self.assertIn("Gitea-28.2.0%20%5BPENDING%5D%20%7C%2028.0.0%20tested-yellow", self.read("README.md")) self.assertIn("Gitea-28.2.0%20%5BPENDING%5D%20%7C%2028.0.0%20tested-yellow", self.read("README.md"))
self.assertIn("Gitea 28.2.0:** [PENDING]", self.read("README.md")) self.assertIn("Gitea 28.2.0:** [PENDING]", self.read("README.md"))
@@ -125,6 +122,12 @@ class TrackerTests(unittest.TestCase):
self.assertIn(("TRACKER", "HISTORY"), {(block.subject, block.content) for block in blocks}) self.assertIn(("TRACKER", "HISTORY"), {(block.subject, block.content) for block in blocks})
self.assertIn(("RELEASE", "HEADER"), {(block.subject, block.content) for block in blocks}) self.assertIn(("RELEASE", "HEADER"), {(block.subject, block.content) for block in blocks})
TRACKER.latest_tested(documents, blocks) TRACKER.latest_tested(documents, blocks)
matrix = next(block for block in blocks if (block.subject, block.content) == ("TRACKER", "VERSION-MAP"))
history = next(block for block in blocks if (block.subject, block.content) == ("TRACKER", "HISTORY"))
self.assertEqual(
TRACKER.table(TRACKER.body(documents[matrix.path], matrix), "VERSION-MAP"),
TRACKER.table(TRACKER.body(documents[history.path], history), "HISTORY"),
)
def test_existing_version_is_idempotent(self): def test_existing_version_is_idempotent(self):
self.assertEqual([], TRACKER.apply_release(self.root, "28.1.0", "2026-10-06")) self.assertEqual([], TRACKER.apply_release(self.root, "28.1.0", "2026-10-06"))
@@ -132,10 +135,10 @@ class TrackerTests(unittest.TestCase):
def test_partial_update_is_repaired(self): def test_partial_update_is_repaired(self):
compatibility = self.root / "COMPATIBILITY.md" compatibility = self.root / "COMPATIBILITY.md"
partial = self.read("COMPATIBILITY.md").replace("| 28.1.0 | [PENDING] Compatibility verification; no tested template release yet |\n", "") partial = self.read("COMPATIBILITY.md").replace("| 28.1.0 | — | [PENDING] | Compatibility verification pending |\n", "")
compatibility.write_text(partial, encoding="utf-8") compatibility.write_text(partial, encoding="utf-8")
self.assertEqual([compatibility], TRACKER.apply_release(self.root, "28.1.0", "2026-10-06")) self.assertEqual([compatibility], TRACKER.apply_release(self.root, "28.1.0", "2026-10-06"))
self.assertIn("| 28.1.0 | [PENDING] Compatibility verification", self.read("COMPATIBILITY.md")) self.assertIn("| 28.1.0 | — | [PENDING] | Compatibility verification pending |", self.read("COMPATIBILITY.md"))
def test_older_version_does_not_rewrite_history(self): def test_older_version_does_not_rewrite_history(self):
self.assertEqual([], TRACKER.apply_release(self.root, "28.0.0", "2026-09-29")) self.assertEqual([], TRACKER.apply_release(self.root, "28.0.0", "2026-09-29"))
.github/scripts/track_gitea_release.py
+4 -4
View File
@@ -24,8 +24,8 @@ BADGE_RE = re.compile(r"Gitea-(\d+\.\d+\.\d+)(?:%20(?:pending|%5BPENDING%5D))?%2
RELEASE_VERSION_RE = re.compile(r"\bv\d+\.\d+\.\d+\b") RELEASE_VERSION_RE = re.compile(r"\bv\d+\.\d+\.\d+\b")
RELEASE_LINK_RE = re.compile(r"\[v\d+\.\d+\.\d+\]\(https://[^)]+/releases/latest\)") RELEASE_LINK_RE = re.compile(r"\[v\d+\.\d+\.\d+\]\(https://[^)]+/releases/latest\)")
TABLES = { TABLES = {
"VERSION-MAP": "| Gitea version | Template release |", "VERSION-MAP": "| Gitea version | Recommended template release | Status | Notes |",
"HISTORY": "| Gitea | Release Date | Mail Template Changes | Breaking? |", "HISTORY": "| Gitea | Release Date | Mail Template Changes | Impact |",
} }
SKIP_DIRECTORIES = frozenset((".git", "node_modules", "vendor", "dist")) SKIP_DIRECTORIES = frozenset((".git", "node_modules", "vendor", "dist"))
@@ -163,13 +163,13 @@ def latest_tested(documents_by_path, blocks):
def update_version_map(content, version, release_date, tested): def update_version_map(content, version, release_date, tested):
if version not in table(content, "VERSION-MAP"): if version not in table(content, "VERSION-MAP"):
content.insert(2, f"| {version} | [PENDING] Compatibility verification; no tested template release yet |\n") content.insert(2, f"| {version} | — | [PENDING] | Compatibility verification pending |\n")
return content return content
def update_history(content, version, release_date, tested): def update_history(content, version, release_date, tested):
if version not in table(content, "HISTORY"): if version not in table(content, "HISTORY"):
content.insert(2, f"| **{version}** | {release_date} | [PENDING] Mail-template compatibility verification | TBD |\n") content.insert(2, f"| **{version}** | {release_date} | [PENDING] Review of mail-template changes | TBD |\n")
return content return content
AGENTS.md
+5 -4
View File
@@ -3,12 +3,12 @@
## Project Overview ## Project Overview
A curated collection of email template themes (10 visual styles) for self-hosted Gitea instances. Each theme contains 11 Go `html/template` files covering all Gitea notification email types. A growing collection of email template themes for self-hosted Gitea instances. Each theme contains 11 Go `html/template` files covering all supported Gitea notification email types.
## Repository Layout ## Repository Layout
``` ```
themes/ # Template themes (10 styles, 11 .tmpl each = 110 source files) themes/ # One directory per theme, with 11 .tmpl files each
aurora/ # Ethereal / Dreamlike aurora/ # Ethereal / Dreamlike
bloom/ # Creative / Startup (glassmorphism) bloom/ # Creative / Startup (glassmorphism)
ember/ # Community / Open Source ember/ # Community / Open Source
@@ -19,6 +19,7 @@ themes/ # Template themes (10 styles, 11 .tmpl each = 110 source fil
neon/ # Cyberpunk / Gaming neon/ # Cyberpunk / Gaming
terminal/ # Developers / Tech terminal/ # Developers / Tech
terra/ # Nature / Sustainability terra/ # Nature / Sustainability
.../ # Additional themes can be added
tools/ # Go CLI tooling (modular; uses urfave/cli/v2) tools/ # Go CLI tooling (modular; uses urfave/cli/v2)
tools.go # Main entry point tools.go # Main entry point
cli/ # CLI subcommands: list, create, delete, preview cli/ # CLI subcommands: list, create, delete, preview
@@ -75,11 +76,11 @@ docs/ # Bilingual documentation (English + Simplified Chinese)
<!-- RELEASE:CURRENT --> <!-- RELEASE:CURRENT -->
- Current template release: **v28.0.0**. - Current template release: **v28.0.0**.
<!-- /RELEASE:CURRENT --> <!-- /RELEASE:CURRENT -->
- v28.0.0 was 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 - v28.0.0 was verified against Gitea 28.0.0. Gitea 28 replaces the mail-template `FileSize` function with `FormatByteSize`; earlier template releases can fail on Gitea 28, and v28.0.0 is not a drop-in replacement for earlier mail contexts. Choose an archive from the per-version matrix in `COMPATIBILITY.md`; v1.27.2 is a known partial fix for push notifications
<!-- TRACKER:UPSTREAM --> <!-- TRACKER:UPSTREAM -->
- Latest upstream Gitea release: 28.1.0 [PENDING]. - Latest upstream Gitea release: 28.1.0 [PENDING].
<!-- /TRACKER:UPSTREAM --> <!-- /TRACKER:UPSTREAM -->
- When a new Gitea version appears, the tracker updates pending rows, marked version lines, and the pending README badge. After verification, update the top `COMPATIBILITY.md` tested range and README tested text/badge; keep unreleased fixes distinct from the published release - When a new Gitea version appears, the tracker adds pending compatibility and history rows and updates marked version lines and the pending README badge. After verification, update that version's matrix row and README tested text/badge; keep unreleased fixes distinct from the published release
- Tag a new release (`vX.Y.Z`) only when the template content itself changes. On the new Gitea host, do not assume tag pushes automatically build or upload archives; verify the Gitea workflow before relying on it - Tag a new release (`vX.Y.Z`) only when the template content itself changes. On the new Gitea host, do not assume tag pushes automatically build or upload archives; verify the Gitea workflow before relying on it
- Before tagging, add `.github/release-notes/vX.Y.Z.md`, run `go test ./...` and `go run . preview all` from `tools/`. The release workflow packages the tag, publishes the reviewed notes, and then updates `RELEASE` blocks on `main` when the host supports those Actions and write permissions; otherwise build/upload and update the labels manually - Before tagging, add `.github/release-notes/vX.Y.Z.md`, run `go test ./...` and `go run . preview all` from `tools/`. The release workflow packages the tag, publishes the reviewed notes, and then updates `RELEASE` blocks on `main` when the host supports those Actions and write permissions; otherwise build/upload and update the labels manually
- Participating Markdown documents declare their blocks in a `DOC-TAGS` JSON comment. Each block uses a paired opening `<!-- SUBJECT:CONTENT -->` and closing `<!-- /SUBJECT:CONTENT -->` comment; its body is the managed text. `TRACKER` handles upstream-pending content, `RELEASE` handles published-template labels, and `TRACKER:LATEST-TESTED` / `TRACKER:LATEST-VERIFIED` are manual-only. Within a document, the first block for a subject/content pair wins - Participating Markdown documents declare their blocks in a `DOC-TAGS` JSON comment. Each block uses a paired opening `<!-- SUBJECT:CONTENT -->` and closing `<!-- /SUBJECT:CONTENT -->` comment; its body is the managed text. `TRACKER` handles upstream-pending content, `RELEASE` handles published-template labels, and `TRACKER:LATEST-TESTED` / `TRACKER:LATEST-VERIFIED` are manual-only. Within a document, the first block for a subject/content pair wins
COMPATIBILITY.md
+56 -51
View File
@@ -3,38 +3,41 @@
This document tracks the compatibility between **Gitea Mail Templates** releases and **Gitea** versions. This document tracks the compatibility between **Gitea Mail Templates** releases and **Gitea** versions.
## Quick Reference ## Compatibility Matrix
| Template Release | Min Gitea | Max Tested Gitea | Status | Choose by your **Gitea version**, not by the highest template tag. [PASS] means a documented compatible combination; [PENDING] has not been verified. Legacy [PASS] entries retain the project's earlier compatibility assessment and were not re-tested on every patch release during this documentation update.
|-----------------|-----------|-----------------|--------|
| **v28.0.0** | **28.0.0** | **28.0.0** | [PASS] Active |
| **v1.27.3** | **1.25.0** | **1.27.3** | [PASS] Superseded; release emails fail on Gitea 28.0.0 (`FileSize` removed) |
| **v1.27.2** | **1.25.0** | **1.27.3** | [WARN] Push notices fail in Bloom, Ember, and Heritage on Gitea 1.27.1+ |
| **v1.0.1** | **1.25.0** | **1.27.0** | [PASS] Superseded; push notices need newer release on 1.27.1+ |
| **v1.0.0** | **1.25.0** | **1.26.4** | [PASS] Superseded |
<!-- 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
The release tag identifies the downloadable template package. The supported Gitea version may be appended in parentheses in this compatibility matrix; the parenthesized version is not a Git tag. An **unreleased** row describes fixes available in the repository but not yet in a downloadable release.
<!-- TRACKER:VERSION-MAP --> <!-- TRACKER:VERSION-MAP -->
| Gitea version | Template release | | Gitea version | Recommended template release | Status | Notes |
|---------------|------------------| |---------------|------------------------------|--------|-------|
| 28.1.0 | [PENDING] Compatibility verification; no tested template release yet | | 28.1.0 | — | [PENDING] | Compatibility verification pending |
| 28.0.0 | **v28.0.0**; older releases use the removed `FileSize` function in release emails | | 28.0.0 | **v28.0.0** | [PASS] | Earlier template releases use the removed `FileSize` mail function |
| 1.27.3 | **v1.27.3**; v1.27.2 has a push-notification issue in three themes | | 1.27.3 | **v1.27.3** | [PASS] | Push-to-PR commit links fixed in every theme |
| 1.27.2 | **v1.27.3**; v1.27.2 has the same issue | | 1.27.2 | **v1.27.3** | [PASS] | Matching v1.27.2 has a push-notification defect in Bloom, Ember, and Heritage |
| 1.27.1 | **v1.27.3**; v1.27.2 has the same issue | | 1.27.1 | **v1.27.3** | [PASS] | Older v1.0.x templates use obsolete push-commit fields; v1.27.2 is only partially fixed |
| 1.27.0 | — | [PENDING] | New commit data shape breaks older push templates; v1.27.3 is a plausible fix but was not release-tested here |
| 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] | — |
<!-- /TRACKER:VERSION-MAP --> <!-- /TRACKER:VERSION-MAP -->
- The [tracker workflow](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/src/branch/main/.github/workflows/gitea-tracker.yml) records new upstream versions as [PENDING] in this table, the history below, and the marked README and AGENTS lines. Its automatic PR creation has not been verified on the new Gitea host; check releases manually until Gitea automation is configured. v1.0.1 retains the pre-1.27 push-commit fields used by the listed Gitea 1.25/1.26 releases. Gitea 1.24.x and earlier use a different custom-mail-template layout and are [UNSUPPORTED]. The v1.0.0 template tag is superseded by v1.0.1; it is not a separate recommendation.
- After verification, update the top **Template Release** row only when that package has been tested against the new Gitea version. Keep fixes on `main` marked **unreleased** until a new tag and downloadable Gitea Release are published; do not assume a tag push uploads archives automatically.
- 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. <!-- TRACKER:LATEST-VERIFIED -->
- 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. > **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. For other Gitea versions, follow the per-version matrix above.
<!-- /TRACKER:LATEST-VERIFIED -->
## Versioning and Known Exceptions
Release tags name actual downloadable packages. A matching version is useful, but it is not a compatibility guarantee: v1.27.2 has a known defect, and there is no v1.27.1 template tag. Use the recommended package in the matrix; do not infer support from a tag number or from the current `main` branch.
- Gitea 1.27.0 changed the push-to-PR commit data shape. Gitea 1.27.1 fixed its **bundled** mail template, but custom overrides still need the new `.UserCommit.GitCommit` path. v1.27.2 updated seven themes; v1.27.3 completed the remaining three. Older v1.0.x templates use the pre-1.27 path. See the [upstream regression report](https://github.com/go-gitea/gitea/issues/38469), [upstream fix](https://github.com/go-gitea/gitea/pull/38467), and [v1.27.2 correction](.github/release-notes/v1.27.2.md).
- Gitea 28.0.0 removed the mail-template `FileSize` function in favor of `FormatByteSize` ([mail function map](https://raw.githubusercontent.com/go-gitea/gitea/v28.0.0/modules/templates/mail.go)). v28.0.0 uses the new function; older template releases can fail when rendering release attachments. Conversely, v28.0.0 is not a drop-in replacement for earlier Gitea mail contexts.
- A source-only fix is **unreleased** until its tag and downloadable archive exist. New upstream versions remain [PENDING] until their compatibility is checked.
## Check Your Gitea Version ## Check Your Gitea Version
@@ -46,33 +49,35 @@ gitea --version
## Gitea Version History — Mail Template Impact ## Gitea Version History — Mail Template Impact
This table describes changes in **Gitea**, not fixes in this template repository. `None` means no relevant new mail-template impact for that Gitea release; the recommended archive is listed in the matrix above.
<!-- TRACKER:HISTORY --> <!-- TRACKER:HISTORY -->
| Gitea | Release Date | Mail Template Changes | Breaking? | | Gitea | Release Date | Mail Template Changes | Impact |
|-------|-------------|----------------------|-----------| |-------|-------------|-----------------------|--------|
| **28.1.0** | 2026-10-06 | [PENDING] Mail-template compatibility verification | TBD | | **28.1.0** | 2026-10-06 | [PENDING] Review of mail-template changes | TBD |
| **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) | | **28.0.0** | 2026-09-29 | `FileSize` replaced by `FormatByteSize`; mail template internals reorganized | **Breaking:** legacy release-attachment templates can fail |
| **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.3** | 2026-08-29 | None | None |
| **1.27.2** | 2026-08-14 | None — security + bug fixes | No | | **1.27.2** | 2026-08-14 | None | None |
| **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) | | **1.27.1** | 2026-07-27 | Bundled push template updated to `.UserCommit.GitCommit` ([fix](https://github.com/go-gitea/gitea/pull/38467)) | **Existing incompatibility persists:** old custom push-to-PR templates can fail |
| **1.27.0** | 2026-07-13 | None — no mail template changes | No | | **1.27.0** | 2026-07-13 | Push commit data moved under `.UserCommit.GitCommit` ([report](https://github.com/go-gitea/gitea/issues/38469)) | **Breaking:** old push-to-PR templates can fail |
| **1.26.4** | 2026-06-21 | None — hotfix release | No | | **1.26.4** | 2026-06-21 | None | None |
| **1.26.3** | 2026-06-20 | None — security release | No | | **1.26.3** | 2026-06-20 | None | None |
| **1.26.2** | 2026-05-20 | None — security + bug fixes | No | | **1.26.2** | 2026-05-20 | None | None |
| **1.26.1** | 2026-04-22 | None — bug fixes | No | | **1.26.1** | 2026-04-22 | None | None |
| **1.26.0** | 2026-04-19 | AppURL cleanup; SanitizeHTML deprecated → use HTMLFormat | No | | **1.26.0** | 2026-04-19 | None | None |
| **1.25.5** | 2026-03-10 | None — security + maintenance | No | | **1.25.5** | 2026-03-10 | None | None |
| **1.25.0** | 2025 | **Directory restructure** — templates moved to `mail/<category>/<type>.tmpl` (PR #35150); subject/body split with `---` separator; template preview support added | **Yes** (structural) | | **1.25.0** | 2025 | Custom-mail paths and subject/body format changed ([refactor](https://github.com/go-gitea/gitea/pull/35150)) | **Breaking:** older template layout is not supported |
| **≤ 1.24.x** | — | Flat directory structure under `custom/templates/mail/` | [UNSUPPORTED] | | **≤ 1.24.x** | — | Legacy custom-mail layout | [UNSUPPORTED] |
<!-- /TRACKER:HISTORY --> <!-- /TRACKER:HISTORY -->
## Template Variable Reference ## 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`). 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) ### Relevant Template Functions
| Function | Since Gitea | Notes | | Function | Gitea version | Notes |
|----------|------------|-------| |----------|---------------|-------|
| `AppName` | ≤ 1.21 | Application name | | `AppName` | ≤ 1.21 | Application name |
| `AppUrl` | ≤ 1.21 | Application base URL | | `AppUrl` | ≤ 1.21 | Application base URL |
| `AppDomain` | ≤ 1.21 | Server domain | | `AppDomain` | ≤ 1.21 | Server domain |
@@ -80,7 +85,8 @@ All 11 template types use only Gitea built-in variables and functions. Verified
| `QueryEscape` | ≤ 1.21 | URL query encoding | | `QueryEscape` | ≤ 1.21 | URL query encoding |
| `PathEscapeSegments` | ≤ 1.21 | Per-segment path encoding | | `PathEscapeSegments` | ≤ 1.21 | Per-segment path encoding |
| `ShortSha` | ≤ 1.21 | Truncated commit hash | | `ShortSha` | ≤ 1.21 | Truncated commit hash |
| `FormatByteSize` | 28.0.0 | Human-readable IEC file size; replaces `FileSize` | | `FileSize` | Before 28.0.0 | Used by older template releases for attachment sizes; unavailable in Gitea 28 mail templates |
| `FormatByteSize` | 28.0.0 | Used by v28.0.0 for attachment sizes; unavailable in earlier Gitea mail templates |
| `HTMLFormat` | ≤ 1.21 | Render string as safe HTML | | `HTMLFormat` | ≤ 1.21 | Render string as safe HTML |
| `Iif` | ≤ 1.21 | Inline conditional | | `Iif` | ≤ 1.21 | Inline conditional |
| `dict` | ≤ 1.21 | Build maps from key-value pairs | | `dict` | ≤ 1.21 | Build maps from key-value pairs |
@@ -89,7 +95,6 @@ All 11 template types use only Gitea built-in variables and functions. Verified
| `SliceUtils` | ≤ 1.21 | Slice manipulation helpers | | `SliceUtils` | ≤ 1.21 | Slice manipulation helpers |
| `JsonUtils` | ≤ 1.21 | JSON helpers | | `JsonUtils` | ≤ 1.21 | JSON helpers |
| `DumpVar` | ≤ 1.21 | Debug variable dump | | `DumpVar` | ≤ 1.21 | Debug variable dump |
| `SanitizeHTML` | ≤ 1.21 | **Deprecated in 1.26** — use `HTMLFormat` |
### Data Contexts by Template ### Data Contexts by Template
@@ -117,12 +122,12 @@ All templates use Gitea's official `mail.*` translation namespace. Every referen
1. **Local validation** — run `go test ./...` and `go run . preview all` from `tools/`; the preview function map mirrors Gitea 28.0.0 1. **Local validation** — run `go test ./...` and `go run . preview all` from `tools/`; the preview function map mirrors Gitea 28.0.0
2. **Source audit** — Template data contexts are cross-referenced against Gitea's `services/mailer/` package 2. **Source audit** — Template data contexts are cross-referenced against Gitea's `services/mailer/` package
3. **Regression tests** — Go tests render push notifications and release attachments in all 10 themes 3. **Regression tests** — Go tests render push notifications and release attachments in every discovered theme
4. **Release checklist** — Each release confirms the max-tested Gitea version in this file 4. **Release checklist** — Each release records its verified Gitea version in the matrix above
## Version Tracking ## Version Tracking
The [tracker workflow](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/src/branch/main/.github/workflows/gitea-tracker.yml) scans all repository Markdown files. A participating document declares its subject/content pairs in a `DOC-TAGS` JSON comment, then encloses each managed body between `<!-- TRACKER:CONTENT -->` and `<!-- /TRACKER:CONTENT -->` (or `RELEASE` equivalents). Only the first block for a repeated pair in a document is processed. `TRACKER:VERSION-MAP` and `TRACKER:HISTORY` add pending rows; `TRACKER:UPSTREAM` updates upstream versions and status; `TRACKER:BADGE` retains the last tested version. On template publication, the [release workflow](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/src/branch/main/.github/workflows/release.yml) updates `RELEASE:HEADER`, `RELEASE:SUMMARY`, and `RELEASE:CURRENT` labels; their links stay fixed at `/releases/latest`, and published tags remain unchanged. `TRACKER:LATEST-TESTED` and `TRACKER:LATEST-VERIFIED` are manual-only and change only after verification. The script rejects undeclared, unknown, or unclosed blocks and missing declarations. Actions execution and write permissions have not been verified on this Gitea host; until then, check [upstream Gitea releases](https://github.com/go-gitea/gitea/releases) and published assets manually. Publish a new template tag only when template content changes (see [Versioning](#versioning)). The [tracker workflow](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/src/branch/main/.github/workflows/gitea-tracker.yml) scans all repository Markdown files. A participating document declares its subject/content pairs in a `DOC-TAGS` JSON comment, then encloses each managed body between `<!-- TRACKER:CONTENT -->` and `<!-- /TRACKER:CONTENT -->` (or `RELEASE` equivalents). Only the first block for a repeated pair in a document is processed. `TRACKER:VERSION-MAP` and `TRACKER:HISTORY` add pending rows; `TRACKER:UPSTREAM` updates upstream versions and status; `TRACKER:BADGE` retains the last tested version. On template publication, the [release workflow](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/src/branch/main/.github/workflows/release.yml) updates `RELEASE:HEADER`, `RELEASE:SUMMARY`, and `RELEASE:CURRENT` labels; their links stay fixed at `/releases/latest`, and published tags remain unchanged. `TRACKER:LATEST-TESTED` and `TRACKER:LATEST-VERIFIED` are manual-only and change only after verification. The script rejects undeclared, unknown, or unclosed blocks and missing declarations. Actions execution and write permissions have not been verified on this Gitea host; until then, check [upstream Gitea releases](https://github.com/go-gitea/gitea/releases) and published assets manually. Publish a new template tag only when template content changes (see [Versioning and Known Exceptions](#versioning-and-known-exceptions)).
## Reporting Issues ## Reporting Issues
CONTRIBUTING.md
+1 -1
View File
@@ -79,7 +79,7 @@ reset flow:
Any readable commit message in semantic format is welcome. Such as: Any readable commit message in semantic format is welcome. Such as:
- `style(horizon|terminal|ember|bloom|heritage|neon|mono|terra|ink|aurora):` — template changes - `style(<name>):` — template changes for a specific theme
- `preview(*):` — preview tooling changes - `preview(*):` — preview tooling changes
- `tools(*):` — Go build script changes - `tools(*):` — Go build script changes
- `docs(*):` — documentation and translations - `docs(*):` — documentation and translations
README.md
+5 -3
View File
@@ -36,6 +36,8 @@ The templates on `main` can replace Gitea's built-in mail templates without patc
| ![Ink](docs/images/ink.png) | **Ink** | Publishing / News / Literature | Editorial print, navy & gold, newspaper layout, drop caps | | ![Ink](docs/images/ink.png) | **Ink** | Publishing / News / Literature | Editorial print, navy & gold, newspaper layout, drop caps |
| ![Aurora](docs/images/aurora.png) | **Aurora** | Premium SaaS / Mindfulness | Ethereal light gradients, deep purple & teal, atmospheric glow | | ![Aurora](docs/images/aurora.png) | **Aurora** | Premium SaaS / Mindfulness | Ethereal light gradients, deep purple & teal, atmospheric glow |
The gallery shows the themes currently included in this repository; new themes can be added as separate directories under `themes/`.
> Images are screenshots from the [local preview](preview/index.html). See [docs/images/README.md](docs/images/README.md) for capture instructions. > Images are screenshots from the [local preview](preview/index.html). See [docs/images/README.md](docs/images/README.md) for capture instructions.
[**Local preview gallery**](preview/index.html) — generate the preview data as described below, then open it in a browser for an interactive style switcher with desktop/mobile viewports and view mode (Modern, Source). [**Local preview gallery**](preview/index.html) — generate the preview data as described below, then open it in a browser for an interactive style switcher with desktop/mobile viewports and view mode (Modern, Source).
@@ -118,7 +120,7 @@ go run . dev
### Features ### Features
- Theme switcher — browse all 10 visual styles - Theme switcher — browse all available visual styles
- Template switcher — all 11 email types - Template switcher — all 11 email types
- View mode — Modern (rendered preview), Source (raw HTML) - View mode — Modern (rendered preview), Source (raw HTML)
- Viewport toggle — Desktop 1386×780 / Mobile 390×780 - Viewport toggle — Desktop 1386×780 / Mobile 390×780
@@ -131,7 +133,7 @@ go run . dev
``` ```
gitea-mail-templates/ gitea-mail-templates/
├── themes/ # 10 visual styles, 11 .tmpl files each ├── themes/ # One directory per visual style, 11 .tmpl files each
│ ├── ... # Custom styles are added here as separate directories │ ├── ... # Custom styles are added here as separate directories
├── preview/ # Live preview SPA ├── preview/ # Live preview SPA
│ ├── index.html # Style/template/client/viewport switcher │ ├── index.html # Style/template/client/viewport switcher
@@ -177,7 +179,7 @@ gitea-mail-templates/
<!-- RELEASE:SUMMARY --> <!-- RELEASE:SUMMARY -->
- **Latest release:** [v28.0.0](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/latest) - **Latest release:** [v28.0.0](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/latest)
<!-- /RELEASE:SUMMARY --> <!-- /RELEASE:SUMMARY -->
- For Gitea 1.25.0–1.27.3, use [v1.27.3](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/tag/v1.27.3); see [COMPATIBILITY.md](COMPATIBILITY.md) for version-specific limits. - For other Gitea versions, check the [per-version compatibility matrix](COMPATIBILITY.md#compatibility-matrix) before choosing an archive; [PENDING] rows have no verified recommendation. The matching v1.27.2 tag has a known push-notification defect.
<!-- TRACKER:UPSTREAM --> <!-- TRACKER:UPSTREAM -->
- **Upstream Gitea 28.1.0:** [PENDING] - **Upstream Gitea 28.1.0:** [PENDING]
<!-- /TRACKER:UPSTREAM --> <!-- /TRACKER:UPSTREAM -->
docs/README.zh-CN.md
+3 -1
View File
@@ -19,6 +19,8 @@
## 风格画廊 ## 风格画廊
下表展示仓库当前收录的主题；新增主题可作为独立目录放在 `themes/` 下，不受现有数量限制。
| 预览 | 风格 | 受众 | 特点 | | 预览 | 风格 | 受众 | 特点 |
|---|---|---|---| |---|---|---|---|
| ![Horizon](images/horizon.png) | **Horizon** | 企业/公司 | 蓝色强调色、石板灰排版、居中卡片 | | ![Horizon](images/horizon.png) | **Horizon** | 企业/公司 | 蓝色强调色、石板灰排版、居中卡片 |
@@ -100,7 +102,7 @@ go run . dev
<!-- RELEASE:SUMMARY --> <!-- RELEASE:SUMMARY -->
- **最新发布版：** [v28.0.0](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/latest) - **最新发布版：** [v28.0.0](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/latest)
<!-- /RELEASE:SUMMARY --> <!-- /RELEASE:SUMMARY -->
- Gitea 1.25.0–1.27.3 请使用 [v1.27.3](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/tag/v1.27.3)；各版本限制参见[兼容性说明](../COMPATIBILITY.md)。 - 其它 Gitea 版本请先查看[逐版本兼容矩阵](../COMPATIBILITY.md#compatibility-matrix)再选择模板压缩包；标记为 [PENDING] 的版本尚无已验证的推荐包。版本号相符的 v1.27.2 存在已知的推送通知问题。
<!-- TRACKER:UPSTREAM --> <!-- TRACKER:UPSTREAM -->
- **上游 Gitea 28.1.0：** [PENDING] - **上游 Gitea 28.1.0：** [PENDING]
<!-- /TRACKER:UPSTREAM --> <!-- /TRACKER:UPSTREAM -->