KenanZhu/GiteaMailTemplates
1
1 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity

chore: refresh docs and adapt workflows for Gitea
Release / Validate Templates (push) Successful in 3m1s
Details
Release / Package & Release (push) Skipped
Details
Release / Update Latest Release Documentation (push) Skipped
Details

Browse Source
This commit is contained in:
KenanZhu committed 2026-10-09 22:02:33 +08:00
1 parent fec3ace600
commit f4d96de79e
14 files changed
+986 -505
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

COMPATIBILITY.md
+28 -15
View File
@@ -1,11 +1,13 @@
# Gitea Compatibility
<!-- DOC-TAGS: {"TRACKER":["LATEST-VERIFIED","VERSION-MAP","HISTORY"]} -->
This document tracks the compatibility between **Gitea Mail Templates** releases and **Gitea** versions.
This document lists supported release combinations, known limitations and the checks used to assess compatibility.
[Project overview](README.md) · [Contributor guide](CONTRIBUTING.md) · [简体中文使用说明](docs/README.zh-CN.md)
## 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.
Select a template release for the Gitea version you run. `[PASS]` records a compatible combination; `[PENDING]` means verification is incomplete. Legacy entries reflect the project's recorded compatibility assessments rather than a fresh test of every patch release.
<!-- TRACKER:VERSION-MAP -->
| Gitea version | Recommended template release | Status | Notes |
@@ -33,21 +35,23 @@ v1.0.1 retains the pre-1.27 push-commit fields used by the listed Gitea 1.25/1.2
## Snapshot-Driven Source Status
The refactor on `main` is **unreleased**. It locks Gitea **v28.0.0**, commit `15b8a5805adf57c5189602008d38cccfd3c795e0`, with 13 mail files (11 entrypoints and 2 shared partials) and 28 official locale files. New source architecture supports Gitea 28+; it does not replace historical release assets or change recommendations in the published matrix.
The source architecture on `main` is **unreleased**. Its lock pins Gitea **v28.0.0**, commit `15b8a5805adf57c5189602008d38cccfd3c795e0`, with 13 mail files (11 entrypoints and 2 shared partials) and 28 locale files. It targets Gitea 28 and later, with each new snapshot requiring review. Historical archives retain the compatibility recorded above.
Theme sources contain CSS and metadata only. A shared framework organizes official mail values/translations into reusable branding, action/fallback and footer controls. Its single alignment layer preserves notification branches, subjects and functional link targets while allowing presentation changes. Only generated `gitea.lock.json` is committed; immutable official inputs are downloaded to ignored `build/upstream/`. Builds fail on checksum, English-key, adapter-reference or unreviewed action-anchor changes. New mail types require framework alignment and fixtures.
Themes contain CSS and metadata. The shared framework adapts official templates into reusable headers, action buttons, fallback links and footers while preserving notification conditions, subjects and functional URLs. Official inputs are downloaded to `build/upstream/` and verified against the committed `gitea.lock.json`. Builds reject mismatched checksums, missing English keys, changed adapter references and unreviewed action anchors. New mail types require framework support and fixtures.
### Translation Behavior
Missing translations in other languages follow the official English fallback and are reported as `[FALLBACK]`. Gitea v28.0.0's Polish `mail.team_invite.text_1` starts with malformed `%[1]z…` instead of `%[1]s`; preview preserves this official defect and reports `[UPSTREAM-WARN]`. The exception matches the exact source text; other formatting defects fail rendering.
Gitea 28.1.0 remains [PENDING]. Updating pending documentation does not synchronize the snapshot or verify a new version.
### Validation Scope
`upstream prepare` requires the committed root lock and creates only an absent cache; `upstream verify` requires both lock and cache and performs no download. Missing locks are not inferred from cache or latest releases. Explicit `upstream sync --tag vX.Y.Z` can initialize or replace the lock, but does not update this matrix or certify compatibility. See [command usage and cache recovery](CONTRIBUTING.md#official-snapshot-updates).
Source validation covers rendering and notification parity across all themes and languages. Optional browser checks cover static and HTTP previews, language switching and mobile layouts. An isolated Gitea smoke test checks template loading and captures a password-reset email. These checks do not establish rendering compatibility with Gmail, Outlook or Apple Mail; test those clients for your deployment. The release workflow does not automatically run the optional browser or real-Gitea suites.
Current-source validation includes all-theme/all-language rendering and notification parity, browser checks for static/HTTP language switching and mobile layouts, and an isolated Gitea 28.0.0 template-loading/password-reset mail smoke test. This does not certify rendering in Gmail, Outlook or Apple Mail; those clients still require deployment-specific testing. The optional real-Gitea and browser suites are not automatically run by the current release workflow.
Snapshot preparation, cache verification and version updates are separate operations. `upstream prepare` uses the root lock to create an absent cache; `upstream verify` checks an existing cache offline. `upstream sync --tag vX.Y.Z` explicitly replaces the snapshot and lock. A successful sync does not certify compatibility or update this matrix. See [command usage and cache recovery](CONTRIBUTING.md#official-snapshot-updates).
## 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.
Release tags identify downloadable packages. Use the matrix to select a supported combination: v1.27.2 has a known defect despite its matching version number, and there is no v1.27.1 template tag. Changes on `main` become part of a release only when a new tag and archive are published.
- 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.
@@ -86,7 +90,7 @@ This table describes changes in **Gitea**, not fixes in this template repository
## Template Variable Reference
The downloaded official inputs define mail variables and calls; themes do not add business variables. The table below summarizes preview contexts. The locked upstream commit, shared alignment layer and strict fixture rendering are authoritative.
Official templates define each mail context. The tables below summarize functions and example data relevant to development; they are not a complete API reference. Check the locked official sources and framework adapter when changing a template or fixture.
### Relevant Template Functions
@@ -126,7 +130,7 @@ The downloaded official inputs define mail variables and calls; themes do not ad
| `repo/issue/assigned` | `Subject`, `Doer`, `Issue`, `Link`, `IsPull`, `CanReply` |
| `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.
`.DisplayName` is available in the authentication mail contexts. Collaborator, transfer, release, workflow, assignment and issue-update templates use the context-specific fields listed above.
### Translation Keys
@@ -142,11 +146,20 @@ Official templates reference `mail.*` keys and `actions.runs.attempt`. AST-based
## 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)).
The [tracker workflow](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/src/branch/main/.github/workflows/gitea-tracker.yml) records upstream releases as pending. Snapshot updates and compatibility verification require a separate review.
Participating Markdown files declare managed subject/content pairs in a `DOC-TAGS` JSON comment. Each body is enclosed by `<!-- TRACKER:CONTENT -->` and `<!-- /TRACKER:CONTENT -->`, or the corresponding `RELEASE` pair. Only the first occurrence of a repeated pair in a document is processed. Undeclared, unknown or unclosed blocks, and missing declared blocks, cause validation to fail.
| Managed blocks | Update policy |
|---|---|
| `TRACKER:VERSION-MAP`, `TRACKER:HISTORY` | Add pending rows for new upstream releases |
| `TRACKER:UPSTREAM` | Update the upstream version and pending status |
| `TRACKER:BADGE` | Update the upstream version while retaining the last tested version |
| `TRACKER:LATEST-TESTED`, `TRACKER:LATEST-VERIFIED` | Updated manually after verification |
| `RELEASE:HEADER`, `RELEASE:SUMMARY`, `RELEASE:CURRENT` | Updated by the release workflow after publication; archive labels are prepared during packaging |
The [release workflow](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/src/branch/main/.github/workflows/release.yml) keeps release links at `/releases/latest` and leaves published tags unchanged. Actions execution and write permissions have not been verified on the configured Gitea host. Until confirmed, check [upstream releases](https://github.com/go-gitea/gitea/releases) and published assets manually. New template tags are published 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
Open an issue with the Gitea version, template release or source commit, affected theme and mail type, language, reproduction steps and error output. Include the mail client for display problems. See the [reporting guide](CONTRIBUTING.md#reporting-problems) for source-build diagnostics.