# Gitea Compatibility

This document tracks the compatibility between **Gitea Mail Templates** releases and **Gitea** versions.

## Quick Reference

| Template Release | Min Gitea | Max Tested Gitea | Status |
|-----------------|-----------|-----------------|--------|
| **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 |

> **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 -->
| Gitea version | Template release |
|---------------|------------------|
| 28.1.0        | [PENDING] Compatibility verification; no tested template release yet |
| 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 |

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

```bash
# On your Gitea server:
gitea --version
# Or check the web UI footer / Site Administration → Monitoring
```

## Gitea Version History — Mail Template Impact

<!-- TRACKER:HISTORY -->
| Gitea | Release Date | Mail Template Changes | Breaking? |
|-------|-------------|----------------------|-----------|
| **28.1.0** | 2026-10-06 | [PENDING] Mail-template compatibility verification | 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) |
| **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) |
| **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 |
| **1.26.2** | 2026-05-20 | None — security + bug fixes | No |
| **1.26.1** | 2026-04-22 | None — bug fixes | No |
| **1.26.0** | 2026-04-19 | AppURL cleanup; SanitizeHTML deprecated → use HTMLFormat | No |
| **1.25.5** | 2026-03-10 | None — security + maintenance | No |
| **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.24.x** | — | Flat directory structure under `custom/templates/mail/` | [UNSUPPORTED] |

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

### Template Functions (available in all templates)

| Function | Since Gitea | Notes |
|----------|------------|-------|
| `AppName` | ≤ 1.21 | Application name |
| `AppUrl` | ≤ 1.21 | Application base URL |
| `AppDomain` | ≤ 1.21 | Server domain |
| `DotEscape` | ≤ 1.21 | Prevents auto-linking of dotted text |
| `QueryEscape` | ≤ 1.21 | URL query encoding |
| `PathEscapeSegments` | ≤ 1.21 | Per-segment path encoding |
| `ShortSha` | ≤ 1.21 | Truncated commit hash |
| `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 |
| `Eval` | ≤ 1.21 | Evaluate template tokens |
| `StringUtils` | ≤ 1.21 | String manipulation helpers |
| `SliceUtils` | ≤ 1.21 | Slice manipulation helpers |
| `JsonUtils` | ≤ 1.21 | JSON helpers |
| `DumpVar` | ≤ 1.21 | Debug variable dump |
| `SanitizeHTML` | ≤ 1.21 | **Deprecated in 1.26** — use `HTMLFormat` |

### Data Contexts by Template

| Template | Key Variables |
|----------|--------------|
| `user/auth/activate` | `DisplayName`, `Code`, `ActiveCodeLives` |
| `user/auth/activate_email` | `DisplayName`, `Code`, `Email`, `ActiveCodeLives` |
| `user/auth/register_notify` | `DisplayName`, `Username` |
| `user/auth/reset_passwd` | `DisplayName`, `Code`, `ResetPwdCodeLives` |
| `org/team_invite` | `Inviter`, `Team`, `Organization`, `InviteURL`, `Invite` |
| `repo/collaborator` | `Subject`, `RepoName`, `Link` |
| `repo/transfer` | `Doer`, `User`, `Repo`, `Link`, `Destination` |
| `repo/release` | `Release` (with `Publisher`, `TagName`, `Title`, `RenderedNote`, `Attachments`), `Link` |
| `repo/actions/workflow_run` | `Run` (with `WorkflowID`, `HTMLURL`), `Jobs`, `RunStatusText` |
| `repo/issue/assigned` | `Doer`, `Issue`, `Link`, `IsPull` |
| `repo/issue/default` | `Doer`, `Issue`, `Link`, `Body`, `ActionName`, `Comment`, `IsPull`, `IsMention`, `ReviewComments`, `CanReply` |

> [WARN] **`.DisplayName`** is not available in collaborator, transfer, release, workflow_run, assigned, and default templates — do not reference it.

### Translation Keys

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

## Version Tracking

The [tracker workflow](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/src/branch/main/.github/workflows/gitea-tracker.yml) scans root-level and `docs/` Markdown for `TRACKER:` markers. `VERSION-MAP` and `HISTORY` add pending rows; `UPSTREAM` updates the latest upstream version and status in English/Chinese README and AGENTS; `BADGE` shows the new version as pending while retaining the last tested version. `LATEST-TESTED` and `LATEST-VERIFIED` are manual-only markers and must change only after compatibility verification. The script rejects unknown or missing required markers and is idempotent. Its GitHub Actions schedule and PR creation have not been verified on this Gitea host; until then, check [upstream Gitea releases](https://github.com/go-gitea/gitea/releases) manually. Publish a new template tag only when template content changes (see [Versioning](#versioning)).

## Reporting Issues

If you find a compatibility problem with a specific Gitea version:

1. Check the [Gitea changelog](https://github.com/go-gitea/gitea/blob/main/CHANGELOG.md) for recent mail template changes
2. Open an issue with: your Gitea version, which template, and the error