chore: prepare v1.27.3 release and guard template publishing

.github/release-notes/v1.27.2.md

@@ -0,0 +1,22 @@
+> **Correction (2026-09-23):** v1.27.2 did not fix every push notification template. Bloom, Ember, and Heritage still used the old commit ID path and can fail to render push notifications on Gitea 1.27.1+. Use v1.27.3 for the fix.
+
+FEATURES
+
+- THEMES (Aurora)
+    - Add `email-text` class to release template paragraphs for consistent typography with the rest of the theme
+
+BUGFIXES
+
+- THEMES
+    - Update push commit data paths in seven themes for Gitea 1.27.1 compatibility (`.ID` → `.UserCommit.GitCommit.ID`); see the correction above for the three remaining themes
+    - Replace `rgba()` colors with `#RRGGBBAA` hex notation across all 10 themes
+
+DOCS
+
+- Track Gitea 1.27.0, 1.27.1, and 1.27.2 compatibility
+- Keep English and Simplified Chinese README and CONTRIBUTING files
+
+
+---
+
+**Full Changelog:** [v1.0.1...v1.27.2](https://github.com/KenanZhu/GiteaMailTemplates/compare/v1.0.1...v1.27.2)

.github/release-notes/v1.27.3.md

@@ -0,0 +1,22 @@
+FEATURES
+
+- RELEASE
+    - Include English and Simplified Chinese README and CONTRIBUTING files in the release archives
+    - Use reviewed release notes in the publishing workflow
+
+BUGFIXES
+
+- THEMES (Bloom, Ember, Heritage)
+    - Fix pull request push notification commit links and abbreviated hashes for Gitea 1.27.1–1.27.3 by reading `.UserCommit.GitCommit.ID`
+- CI
+    - Add a push notification regression test covering all 10 themes and run Go tests before packaging a release
+
+DOCS
+
+- Verify compatibility with Gitea 1.27.3; its mail templates, mailer, and locale files are unchanged from 1.27.2
+- Correct the compatibility matrix to distinguish the affected v1.27.2 archive from this fixed release
+
+
+---
+
+**Full Changelog:** [v1.27.2...v1.27.3](https://github.com/KenanZhu/GiteaMailTemplates/compare/v1.27.2...v1.27.3)

.github/workflows/gitea-tracker.yml

@@ -80,30 +80,12 @@ jobs:
           ROW="| **${NEW}** | ${TODAY} | ⏳ Pending Verification | TBD |"
           sed -i "${INSERT}a ${ROW}" COMPATIBILITY.md
 
-      - name: COMPATIBILITY.md — latest verified note
+      - name: README.md — pending badge
-        if: steps.version.outputs.skip != 'true'
-        run: |
-          NEW="${{ steps.version.outputs.new_version }}"
-          # Update version inline on the line with TRACKER:LATEST-VERIFIED
-          sed -i "/TRACKER:LATEST-VERIFIED/s/Gitea [0-9.]*/Gitea ${NEW}/" COMPATIBILITY.md
-
-      - name: README.md — badge and latest tested
         if: steps.version.outputs.skip != 'true'
         run: |
           NEW="${{ steps.version.outputs.new_version }}"
           # Badge: update version, change label tested→pending, color blue→yellow
           sed -i "/TRACKER:BADGE/s/%20[0-9a-z.-]*%20tested-blue/%20${NEW}%20pending-yellow/" README.md
-          # Latest tested: update version on the TRACKER:LATEST-TESTED line
-          sed -i "/TRACKER:LATEST-TESTED/s/Gitea [0-9.]*/Gitea ${NEW}/" README.md
-
-
-      - name: README translations — latest tested
-        if: steps.version.outputs.skip != 'true'
-        run: |
-          NEW="${{ steps.version.outputs.new_version }}"
-          for f in docs/README.zh-CN.md; do
-            sed -i "/TRACKER:LATEST-TESTED/s/Gitea [0-9.]*/Gitea ${NEW}/" "$f"
-          done
 
       - name: Create Pull Request
         if: steps.version.outputs.skip != 'true'
@@ -117,21 +99,24 @@ jobs:
 
             This PR:
             - Updates the compatibility matrix in `COMPATIBILITY.md`
-            - Updates version badges in `README.md` and translations
+            - Marks the new version as pending in the `README.md` badge
             - Marks the new version as **⏳ Pending Verification**
 
             ## Verification Checklist
             - [ ] Check [Gitea changelog](https://github.com/go-gitea/gitea/blob/main/CHANGELOG.md) for mail template changes
             - [ ] Review diff of official templates: `git diff v${{ steps.version.outputs.current_version }}..v${{ steps.version.outputs.new_version }} -- templates/mail/ services/mailer/`
             - [ ] Run `cd tools && go run . preview all` to confirm templates still render
+            - [ ] Run `cd tools && go test ./...` to verify push-notification data paths
             - [ ] Update status from ⏳ to ✅ (compatible) or ❌ (breaking) in COMPATIBILITY.md
             - [ ] Update the `Mail Template Changes` and `Breaking?` columns with accurate notes
+            - [ ] After verification, update `TRACKER:LATEST-VERIFIED` and the English/Chinese `TRACKER:LATEST-TESTED` lines; switch the README badge from pending to tested
 
             ## Semantic tracking
-            Once verified, update the tracked Gitea version (release numbers stay unchanged):
+            Once verified, update the tracked Gitea version:
-            - [ ] Update the parenthesized Gitea version on the active **Template Release** row in `COMPATIBILITY.md` (e.g. `v1.0.1(v${{ steps.version.outputs.new_version }})`)
+            - [ ] If templates changed, mark the top **Template Release** row `Unreleased` until the fix is tagged; if no change is needed, retain the verified release tag
-            - [ ] Update the README release line and badge to the new version
+            - [ ] Update the README release status and compatibility matrix to distinguish source fixes from published packages
-            - [ ] Tag a new release only if the template content itself changed — `git tag vX.Y.Z && git push origin vX.Y.Z` (the release workflow packages automatically)
+            - [ ] Write `.github/release-notes/vX.Y.Z.md` before tagging; the release workflow uses this file for the published notes
+            - [ ] Tag a new release when shipping template fixes — `git tag vX.Y.Z && git push origin vX.Y.Z` (the release workflow packages automatically)
           labels: compatibility, automated
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yml

@@ -16,6 +16,10 @@ jobs:
         with:
           go-version: '1.21'
 
+      - name: Test — mail template data contexts
+        working-directory: tools
+        run: go test ./...
+
       - name: Lint — render all templates
         working-directory: tools
         run: go run . preview all
@@ -30,20 +34,25 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Verify release notes
+        run: test -s ".github/release-notes/${GITHUB_REF_NAME}.md"
+
       - name: Package themes/
         run: |
           VERSION=${GITHUB_REF#refs/tags/}
           ARCHIVE="gitea-mail-templates-${VERSION}"
-          mkdir -p "dist/${ARCHIVE}"
+          mkdir -p "dist/${ARCHIVE}/docs"
-          cp -r themes LICENSE README.md COMPATIBILITY.md "dist/${ARCHIVE}/"
+          cp -r themes LICENSE README.md CONTRIBUTING.md COMPATIBILITY.md "dist/${ARCHIVE}/"
+          cp docs/README.zh-CN.md docs/CONTRIBUTING.zh-CN.md "dist/${ARCHIVE}/docs/"
           cd dist
           zip -r "${ARCHIVE}.zip" "${ARCHIVE}"
           tar -czf "${ARCHIVE}.tar.gz" "${ARCHIVE}"
 
       - name: Create Release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v3
         with:
           files: dist/*.zip,dist/*.tar.gz
-          generate_release_notes: true
+          fail_on_unmatched_files: true
+          body_path: .github/release-notes/${{ github.ref_name }}.md
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

AGENTS.md

@@ -66,10 +66,11 @@ docs/               # Bilingual documentation (English + Simplified Chinese)
 
 ## Versioning
 
-- Release numbers stay on the project's own scheme; the supported Gitea version is appended in parentheses — `v1.0.1(v1.27.2)` means release `v1.0.1` tracks Gitea `1.27.2`
+- Release tags identify actual downloadable packages; the compatibility matrix distinguishes released tags from source-only fixes
-- The current release is **v1.0.1** (tracks Gitea 1.27.2); the quick-reference table in `COMPATIBILITY.md` lists it first — the tracker workflow updates that row by position
+- 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
-- When a new Gitea version is verified compatible: update the parenthesized Gitea version in the active `COMPATIBILITY.md` row, plus the README release line and badge
+- 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
 - Keep the `TRACKER:` markers in `COMPATIBILITY.md` / `README.md` adjacent to their rows so the automated workflow keeps parsing them
 
 ## Commit Conventions

COMPATIBILITY.md

@@ -7,23 +7,26 @@ 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.0.1(v1.27.2)** | **1.25.0** | **1.27.2** | ✅ Active |
+| **v1.27.3** | **1.25.0** | **1.27.3** | ✅ Active |
+| **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:** All 11 templates pass validation against Gitea 1.27.2 data contexts. <!-- TRACKER:LATEST-VERIFIED -->
+> **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 -->
 
 ## Versioning
 
-From **1.27.1** onward, template releases are **semantically tracked** against Gitea: the release keeps its own number, and the supported Gitea version is appended in parentheses — `v1.0.1(v1.27.2)` means release `v1.0.1` is the version to use with Gitea `1.27.2`.
+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.
 
 | Gitea version | Template release |
 |---------------|------------------|
-| 1.27.2        | **v1.0.1(v1.27.2)** |
+| 1.27.3        | **v1.27.3**; v1.27.2 has a push-notification issue in three themes |
-| 1.27.1        | **v1.0.1(v1.27.1)** |
+| 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 |
 
 - 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 parenthesized Gitea version on the active **Template Release** row. A new release (`vX.Y.Z`) is only tagged when the template content itself changes — the [release workflow](.github/workflows/release.yml) packages the archive automatically on tag push.
+- 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.
-- Releases before Gitea 1.27.1 predate semantic tracking and keep their plain version numbers in the matrix.
+- 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.
 
 ## Check Your Gitea Version
 
@@ -38,8 +41,9 @@ gitea --version
 <!-- TRACKER:VERSION-INSERT OFFSET=2 -->
 | Gitea | Release Date | Mail Template Changes | Breaking? |
 |-------|-------------|----------------------|-----------|
+| **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 | Fixed push commit data paths: .ID → .UserCommit.GitCommit.ID (#38467) | 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) |
 | **1.27.0** | 2026-07-13 | None — no mail template changes | No |
 | **1.26.4** | 2026-06-21 | None — hotfix release | No |
 | **1.26.3** | 2026-06-20 | None — security release | No |
@@ -106,7 +110,7 @@ All templates use Gitea's official `mail.*` translation namespace. Keys are stab
 
 ## Automated Tracking
 
-A [workflow](.github/workflows/gitea-tracker.yml) runs daily (UTC 08:00) to detect new Gitea releases. When a new version is found, it automatically creates a PR updating the matrix and badges with a **⏳ Pending Verification** status. Manual trigger is also available via `workflow_dispatch`. Once verification passes, release the templates under the same version number (see [Versioning](#versioning)).
+A [workflow](.github/workflows/gitea-tracker.yml) runs daily (UTC 08:00) to detect new Gitea releases. When a new version is found, it automatically creates a PR updating the matrix and badges with a **⏳ Pending Verification** status. Manual trigger is also available via `workflow_dispatch`. Once verification passes, update the compatibility matrix; publish a new template tag when template changes require a release (see [Versioning](#versioning)).
 
 ## Reporting Issues
 

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.2%20tested-blue)](COMPATIBILITY.md) <!-- TRACKER:BADGE -->
+[![Gitea](https://img.shields.io/badge/Gitea-1.25+%20%7C%201.27.3%20tested-blue)](COMPATIBILITY.md) <!-- TRACKER:BADGE -->
 
-> **Release v1.0.1 — tracks Gitea 1.27.2 — 110 template files, 10 visual styles, 11 email types each**
+> **Release v1.27.3 — verified with Gitea 1.27.3 — 110 template files, 10 visual styles, 11 email types each.**
 
 ---
 
@@ -12,7 +12,7 @@ A curated collection of professionally designed, audience-driven email templates
 
 Most self-hosted Gitea instances use the default plain email templates. This project provides **ready-to-deploy, visually polished alternatives** — each designed for a specific community or audience, so you can pick the one that feels right for your users.
 
-Every template is a drop-in replacement. All Go template variables, translation keys, and Gitea data contexts are fully compatible. **No patches, no plugins, no forks required.**
+The templates on `main` can replace Gitea's built-in mail templates without patches, plugins, or forks. Check the [compatibility matrix](COMPATIBILITY.md) before using a published archive; older releases may have version-specific limitations.
 
 ---
 
@@ -164,9 +164,9 @@ gitea-mail-templates/
 ## Compatibility
 
 - **Gitea 1.25+** — matches the refactored mail template directory structure (v1.25)
-- **Latest tested:** Gitea 1.27.2 <!-- TRACKER:LATEST-TESTED -->
+- **Latest tested:** Gitea 1.27.3 <!-- TRACKER:LATEST-TESTED -->
-- **Versioning:** releases are semantically tracked — Gitea 1.27.2 → template release v1.0.1(v1.27.2) (see [COMPATIBILITY.md](COMPATIBILITY.md))
+- **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))
-- 100% variable-compatible with official Gitea templates — see [COMPATIBILITY.md](COMPATIBILITY.md) for the full matrix
+- 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) 实例精心设计、面向不同受众的邮件模板集合。
 
-> **110 个模板文件 — 10 种视觉风格，每种 11 种邮件类型**
+> **发布版 v1.27.3 — 已通过 Gitea 1.27.3 兼容性检查 — 110 个模板文件、10 种视觉风格、每种 11 种邮件类型**
 
 ---
 
@@ -10,7 +10,7 @@
 
 大多数自托管 Gitea 实例使用默认的纯文本邮件模板。本项目提供了**开箱即用、视觉精美的替代方案**——每种方案都针对特定社区或受众设计，您可以选择最适合您用户的风格。
 
-每个模板都是直接替换。所有 Go 模板变量、翻译键和 Gitea 数据上下文完全兼容。**无需补丁、无需插件、无需 fork。**
+`main` 分支中的模板可直接替换 Gitea 内置邮件模板，**无需补丁、插件或 fork**。使用已发布的压缩包前，请先查看[兼容性说明](../COMPATIBILITY.md)，了解旧版本的限制。
 
 ---
 
@@ -79,9 +79,9 @@ cd tools && go run . dev
 ## 兼容性
 
 - **Gitea 1.25+** — v1.25 引入的邮件模板目录结构
-- **最新测试：** Gitea 1.27.2<!-- TRACKER:LATEST-TESTED -->
+- **最新测试：** Gitea 1.27.3<!-- TRACKER:LATEST-TESTED -->
-- **版本号：** 发布版本语义化追踪 Gitea 版本 — Gitea 1.27.2 → 模板发布版 v1.0.1(v1.27.2)（详见 [COMPATIBILITY.md](COMPATIBILITY.md)）
+- **最新发布版：** [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 官方模板 100% 兼容 — 详见 [COMPATIBILITY.md](COMPATIBILITY.md)
+- 当前源码使用 Gitea 官方模板的数据路径；各发布版的限制详见 [兼容性说明](../COMPATIBILITY.md)
 
 ## 许可证
 

themes/bloom/mail/repo/issue/default.tmpl

@@ -124,8 +124,8 @@
           <ul class="commit-list">
           {{range .Comment.Commits}}
             <li class="commit-item">
-              <a href="{{$.Comment.Issue.PullRequest.BaseRepo.HTMLURL}}/commit/{{.ID}}" class="commit-link">
+              <a href="{{$.Comment.Issue.PullRequest.BaseRepo.HTMLURL}}/commit/{{.UserCommit.GitCommit.ID}}" class="commit-link">
-                {{ShortSha .ID.String}}
+                {{ShortSha .UserCommit.GitCommit.ID.String}}
               </a>  &mdash;  {{.UserCommit.GitCommit.MessageTitle}}
             </li>
           {{end}}

themes/ember/mail/repo/issue/default.tmpl

@@ -129,8 +129,8 @@
           <ul class="commit-list">
           {{range .Comment.Commits}}
             <li class="commit-item">
-              <a href="{{$.Comment.Issue.PullRequest.BaseRepo.HTMLURL}}/commit/{{.ID}}" class="commit-link">
+              <a href="{{$.Comment.Issue.PullRequest.BaseRepo.HTMLURL}}/commit/{{.UserCommit.GitCommit.ID}}" class="commit-link">
-                {{ShortSha .ID.String}}
+                {{ShortSha .UserCommit.GitCommit.ID.String}}
               </a>  &mdash;  {{.UserCommit.GitCommit.MessageTitle}}
             </li>
           {{end}}

themes/heritage/mail/repo/issue/default.tmpl

@@ -122,8 +122,8 @@
           <ul class="commit-list">
           {{range .Comment.Commits}}
             <li class="commit-item">
-              <a href="{{$.Comment.Issue.PullRequest.BaseRepo.HTMLURL}}/commit/{{.ID}}" class="commit-link">
+              <a href="{{$.Comment.Issue.PullRequest.BaseRepo.HTMLURL}}/commit/{{.UserCommit.GitCommit.ID}}" class="commit-link">
-                {{ShortSha .ID.String}}
+                {{ShortSha .UserCommit.GitCommit.ID.String}}
               </a>  &mdash;  {{.UserCommit.GitCommit.MessageTitle}}
             </li>
           {{end}}

tools/preview/push_test.go

@@ -0,0 +1,67 @@
+package preview
+
+import (
+	"html/template"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"gitea-mail-templates/tools/config"
+)
+
+type testCommitID string
+
+func (id testCommitID) String() string { return string(id) }
+
+// Exercise the push-only branch with Gitea's nested commit data shape.
+// The normal preview fixture has no commits, so it cannot catch stale .ID paths.
+func TestPushCommitTemplates(t *testing.T) {
+	cfg, err := config.Load(filepath.Join("..", "data", "templates_config.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	const sha = "0123456789abcdef0123456789abcdef01234567"
+	data := cfg.Templates["default"].Params
+	data["ActionName"] = "push"
+	data["locale"] = Locale{}
+	comment := data["Comment"].(map[string]any)
+	comment["Commits"] = []any{map[string]any{
+		"UserCommit": map[string]any{
+			"GitCommit": map[string]any{
+				"ID":           testCommitID(sha),
+				"MessageTitle": "Test push commit",
+			},
+		},
+	}}
+	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) {
+			path := filepath.Join(themesDir, theme.Name(), "mail", "repo", "issue", "default.tmpl")
+			content, err := os.ReadFile(path)
+			if err != nil {
+				t.Fatal(err)
+			}
+			tmpl, err := template.New("push").Funcs(TemplateFuncs).Parse(string(content))
+			if err != nil {
+				t.Fatal(err)
+			}
+			var html strings.Builder
+			if err := tmpl.Execute(&html, data); err != nil {
+				t.Fatal(err)
+			}
+			if !strings.Contains(html.String(), "/commit/"+sha) || !strings.Contains(html.String(), sha[:10]) {
+				t.Fatal("push commit link or abbreviated hash missing from rendered email")
+			}
+		})
+	}
+}