72 lines
6.2 KiB
Markdown
72 lines
6.2 KiB
Markdown
# Gitea Compatibility
|
|
---
|
|
[简体中文](docs/COMPATIBILITY.zh-CN.md)
|
|
|
|
This document describes the compatibility of Gitea Mail Templates with different Gitea versions.
|
|
|
|
## Compatibility Matrix
|
|
|
|
Select the recommended template release for the Gitea version you run. `[PASS]` identifies a combination recorded as compatible; `[PENDING]` means verification is incomplete.
|
|
|
|
> [!NOTE]
|
|
> This project generally aligns template version numbers with Gitea version numbers. However, not every Gitea release introduces mail template changes, so the compatibility matrix recommends template versions based on compatibility assessments; their version numbers may differ from the Gitea version you run. Historical entries reflect existing assessments and do not imply that every listed Gitea version is retested for each template release.
|
|
|
|
| Gitea version | Recommended template release | Status | Notes |
|
|
|---|---|---|---|
|
|
| 28.2.0 | [**v28.1.0**](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/tag/v28.1.0) | [PASS] | Mail templates, template function registrations and mail translation keys are unchanged from 28.1.0 |
|
|
| 28.1.0 | [**v28.1.0**](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/tag/v28.1.0) | [PASS] | - |
|
|
| 28.0.0 | [**v28.1.0**](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/tag/v28.1.0) | [PASS] | Gitea replaced the mail function `FileSize` with `FormatByteSize` |
|
|
| 1.27.3 | [**v1.27.3**](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/tag/v1.27.3) | [PASS] | Pull request push notification commit links fixed in every theme |
|
|
| 1.27.2 | [**v1.27.3**](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/tag/v1.27.3) | [PASS] | The matching v1.27.2 template release has push notification defects in Bloom, Ember and Heritage |
|
|
| 1.27.1 | [**v1.27.3**](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/tag/v1.27.3) | [PASS] | Older v1.0.x templates use obsolete push commit fields |
|
|
| 1.27.0 | — | [PENDING] | Gitea uses a new commit data structure; v1.27.3 may be compatible but has not been verified against this version |
|
|
| 1.26.4 | [**v1.0.1**](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/tag/v1.0.1) | [PASS] | — |
|
|
| 1.26.3 | [**v1.0.1**](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/tag/v1.0.1) | [PASS] | — |
|
|
| 1.26.2 | [**v1.0.1**](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/tag/v1.0.1) | [PASS] | — |
|
|
| 1.26.1 | [**v1.0.1**](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/tag/v1.0.1) | [PASS] | — |
|
|
| 1.26.0 | [**v1.0.1**](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/tag/v1.0.1) | [PASS] | — |
|
|
| 1.25.5 | [**v1.0.1**](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/tag/v1.0.1) | [PASS] | — |
|
|
| 1.25.0 | [**v1.0.1**](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/releases/tag/v1.0.1) | [PASS] | — |
|
|
|
|
> [!NOTE]
|
|
> Gitea 1.24.x and earlier use a different mail template layout and are `[UNSUPPORTED]`; Gitea Mail Templates no longer provides separate support for them.
|
|
|
|
## Gitea Version History — Mail Template Impact
|
|
|
|
This table describes changes in **Gitea**, not fixes in this template repository. “None” means that the Gitea version introduces no relevant mail template changes; recommended archives are listed in the compatibility matrix above.
|
|
|
|
| Gitea | Release date | Mail template changes | Impact |
|
|
|---|---|---|---|
|
|
| **28.2.0** | 2026-10-18 | No template interface changes | Custom-watch notification recipient rules and incoming reply token validation changed; existing templates are unaffected |
|
|
| **28.1.0** | 2026-10-06 | None | None |
|
|
| **28.0.0** | 2026-09-29 | Mail function `FileSize` renamed to `FormatByteSize` ([PR](https://github.com/go-gitea/gitea/pull/39083)) | **Breaking change:** old release attachment templates fail |
|
|
| | | Introduced `templates/mail/base/` ([PR](https://github.com/go-gitea/gitea/pull/38396)) | **Breaking change:** older Gitea versions cannot directly use the new mail templates |
|
|
| **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 use `.UserCommit.GitCommit` ([PR](https://github.com/go-gitea/gitea/pull/38467)) | **Breaking change: an existing defect remains unresolved.** Old custom pull request push templates can fail |
|
|
| **1.27.0** | 2026-07-13 | Push commit data moved under `.UserCommit.GitCommit` ([ISSUE](https://github.com/go-gitea/gitea/issues/38469)) | **Breaking change:** old pull request push templates 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 ([PR](https://github.com/go-gitea/gitea/pull/35150)) | **Breaking change:** older template layouts are unsupported |
|
|
| **≤ 1.24.x** | — | Legacy custom mail layout | [UNSUPPORTED] |
|
|
|
|
## Template Variable Reference
|
|
|
|
> [!NOTE]
|
|
> Mail templates, context construction, template functions and translation keys were checked against the [Gitea 28.1.0 to 28.2.0 source diff](https://github.com/go-gitea/gitea/compare/v28.1.0...v28.2.0). Version 28.2.0 changes [email notification rules for custom watches](https://github.com/go-gitea/gitea/pull/39837) and [incoming email token validation](https://github.com/go-gitea/gitea/pull/39841), without changing the variables, functions or translation keys required by existing mail templates. Source build inputs are locked to v28.2.0; the published v28.1.0 templates remain usable.
|
|
|
|
Official templates define the context for each mail type. For specific mail templates, functions and variables used during development, refer to the official mail template documentation [1](#notes).
|
|
|
|
## Translation Keys
|
|
|
|
Official templates reference `mail.*` and `actions.runs.attempt`. AST-based checks cover `.locale.Tr`, `$.locale.Tr` and both plural keys in `TrN`, including nested pipelines. Every referenced key must exist in the locked English catalog.
|
|
|
|
---
|
|
### Notes
|
|
|
|
[1](#notes): [Mail templates | Gitea Documentation](https://docs.gitea.com/administration/mail-templates/)
|