# Gitea Compatibility
<!-- DOC-TAGS: {"TRACKER":["LATEST-VERIFIED","VERSION-MAP","HISTORY"]} -->

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 |

<!-- 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 -->
| 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 |
<!-- /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.
- 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] |
<!-- /TRACKER:HISTORY -->

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

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