138 lines
10 KiB
Markdown
138 lines
10 KiB
Markdown
# Gitea Compatibility
|
|
<!-- DOC-TAGS: {"TRACKER":["LATEST-VERIFIED","VERSION-MAP","HISTORY"]} -->
|
|
|
|
This document tracks the compatibility between **Gitea Mail Templates** releases and **Gitea** versions.
|
|
|
|
## Compatibility Matrix
|
|
|
|
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.
|
|
|
|
<!-- TRACKER:VERSION-MAP -->
|
|
| Gitea version | Recommended template release | Status | Notes |
|
|
|---------------|------------------------------|--------|-------|
|
|
| 28.1.0 | — | [PENDING] | Compatibility verification pending |
|
|
| 28.0.0 | **v28.0.0** | [PASS] | Earlier template releases use the removed `FileSize` mail function |
|
|
| 1.27.3 | **v1.27.3** | [PASS] | Push-to-PR commit links fixed in every theme |
|
|
| 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** | [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 -->
|
|
|
|
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.
|
|
|
|
<!-- 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. 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
|
|
|
|
```bash
|
|
# On your Gitea server:
|
|
gitea --version
|
|
# Or check the web UI footer / Site Administration → Monitoring
|
|
```
|
|
|
|
## 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 -->
|
|
| Gitea | Release Date | Mail Template Changes | Impact |
|
|
|-------|-------------|-----------------------|--------|
|
|
| **28.1.0** | 2026-10-06 | [PENDING] Review of mail-template changes | TBD |
|
|
| **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 | None | None |
|
|
| **1.27.2** | 2026-08-14 | None | None |
|
|
| **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 | 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 | None |
|
|
| **1.26.3** | 2026-06-20 | None | None |
|
|
| **1.26.2** | 2026-05-20 | None | None |
|
|
| **1.26.1** | 2026-04-22 | None | None |
|
|
| **1.26.0** | 2026-04-19 | None | None |
|
|
| **1.25.5** | 2026-03-10 | None | None |
|
|
| **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** | — | Legacy custom-mail layout | [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`).
|
|
|
|
### Relevant Template Functions
|
|
|
|
| Function | Gitea version | 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 |
|
|
| `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 |
|
|
| `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 |
|
|
|
|
### 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 every discovered theme
|
|
4. **Release checklist** — Each release records its verified Gitea version in the matrix above
|
|
|
|
## 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 and Known Exceptions](#versioning-and-known-exceptions)).
|
|
|
|
## 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
|