docs: adopt semantic versioning — release 1.27.1 tracks Gitea 1.27.1

Templates were re-checked against the local gitea clone (v1.27.1 tag): all
46 translation keys exist in locale_en-US, all data paths match the official
templates, and all 110 templates render via `go run . preview all` — no
template changes required.

From now on release versions mirror the Gitea version they support:
- COMPATIBILITY.md: quick reference now leads with release 1.27.1
  (max tested Gitea 1.27.1, active), v1.0.x marked superseded; new
  Versioning section documents the scheme
- README: release version in header + versioning bullet
- Tracker workflow PR body: added semantic-versioning release checklist
  (bump Template Release column, tag vX.Y.Z)

Co-Authored-By: Claude <noreply@anthropic.com>

.github/workflows/gitea-tracker.yml

@@ -126,6 +126,11 @@ jobs:
             - [ ] Run `cd tools && go run . preview all` to confirm templates still render
             - [ ] Update status from ⏳ to ✅ (compatible) or ❌ (breaking) in COMPATIBILITY.md
             - [ ] Update the `Mail Template Changes` and `Breaking?` columns with accurate notes
+
+            ## Release (semantic versioning)
+            Once verified, releases mirror the Gitea version:
+            - [ ] Bump the **Template Release** column in `COMPATIBILITY.md` to **${{ steps.version.outputs.new_version }}**
+            - [ ] Tag the release with the same number: `git tag v${{ steps.version.outputs.new_version }} && git push origin v${{ steps.version.outputs.new_version }}` — the release workflow packages the archive automatically
           labels: compatibility, automated
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

AGENTS.md

@@ -64,6 +64,13 @@ docs/               # Multi-language documentation
 - `tools/preview/server.go` pure Go dev server with SSE live reload and in-process template re-rendering
 - Uses Go's native `html/template` package for template rendering
 
+## Versioning
+
+- Release versions **mirror the Gitea version they support**: Gitea `X.Y.Z` → template release `X.Y.Z` (git tag `vX.Y.Z`)
+- The current release is **1.27.1** (tracks Gitea 1.27.1); the quick-reference table in `COMPATIBILITY.md` lists it first — the tracker workflow updates that row by position
+- When a new Gitea version is verified compatible: bump the **Template Release** column in `COMPATIBILITY.md`, update the README release line and badge, then tag `vX.Y.Z` (the release workflow packages automatically on tag push)
+- Keep the `TRACKER:` markers in `COMPATIBILITY.md` / `README.md` adjacent to their rows so the automated workflow keeps parsing them
+
 ## Commit Conventions
 - `style(name):` — template changes for a specific theme
 - `preview:` — preview tooling changes

COMPATIBILITY.md

@@ -7,11 +7,24 @@ 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**      | **1.25.0** | **1.27.1** | ✅ Active |
+| **1.27.1**      | **1.25.0** | **1.27.1** | ✅ Active |
+| **v1.0.1**      | **1.25.0** | **1.27.1** | ✅ Superseded |
 | **v1.0.0**      | **1.25.0** | **1.26.4** | ✅ Superseded |
 
 > **Latest verified:** All 11 templates pass validation against Gitea 1.27.1 data contexts. <!-- TRACKER:LATEST-VERIFIED -->
 
+## Versioning
+
+From **1.27.1** onward, Gitea Mail Templates releases **mirror the Gitea version they support**: Gitea `X.Y.Z` uses template release `X.Y.Z` (tagged `vX.Y.Z`).
+
+| Gitea version | Template release |
+|---------------|------------------|
+| 1.27.1        | **1.27.1**       |
+
+- The [tracker workflow](.github/workflows/gitea-tracker.yml) opens a PR when a new Gitea release appears, marking it ⏳ Pending Verification.
+- After verification, bump the **Template Release** column to the new version and tag it with the same number — the [release workflow](.github/workflows/release.yml) packages the archive automatically on tag push.
+- Releases before 1.27.1 used an independent numbering scheme (`v1.0.x`) and remain listed in the matrix for reference.
+
 ## Check Your Gitea Version
 
 ```bash
@@ -92,7 +105,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`.
+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)).
 
 ## Reporting Issues
 

README.md

@@ -4,7 +4,7 @@ A curated collection of professionally designed, audience-driven email templates
 
 [![Gitea](https://img.shields.io/badge/Gitea-1.25+%20%7C%201.27.1%20tested-blue)](COMPATIBILITY.md) <!-- TRACKER:BADGE -->
 
-> **110 template files — 10 visual styles, 11 email types each**
+> **Release 1.27.1 — 110 template files, 10 visual styles, 11 email types each**
 
 ---
 
@@ -165,6 +165,7 @@ gitea-mail-templates/
 
 - **Gitea 1.25+** — matches the refactored mail template directory structure (v1.25)
 - **Latest tested:** Gitea 1.27.1 <!-- TRACKER:LATEST-TESTED -->
+- **Versioning:** releases mirror the Gitea version they support — Gitea 1.27.1 → template release 1.27.1 (see [COMPATIBILITY.md](COMPATIBILITY.md))
 - 100% variable-compatible with official Gitea templates — see [COMPATIBILITY.md](COMPATIBILITY.md) for the full matrix
 - Uses only built-in Gitea template functions and official translation keys
 - No custom template functions or locale patches required

docs/README.zh-CN.md

@@ -80,6 +80,7 @@ cd tools && go run . dev
 
 - **Gitea 1.25+** — v1.25 引入的邮件模板目录结构
 - **最新测试：** Gitea 1.27.1<!-- TRACKER:LATEST-TESTED -->
+- **版本号：** 发布版本与所支持的 Gitea 版本一致 — Gitea 1.27.1 → 模板发布版 1.27.1（详见 [COMPATIBILITY.md](COMPATIBILITY.md)）
 - 与 Gitea 官方模板 100% 兼容 — 详见 [COMPATIBILITY.md](COMPATIBILITY.md)
 
 ## 许可证