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

CONTRIBUTING.md
+163 -83
View File
@@ -1,79 +1,130 @@
# Contributing to Gitea Mail Templates
## Adding a Theme
[简体中文](docs/CONTRIBUTING.zh-CN.md) · [Project overview](README.md) · [Compatibility](COMPATIBILITY.md)
1. Run `cd tools && go run . create <name>` to create a framework-backed theme.
2. Edit `themes/<name>/theme.json` and `theme.css`.
3. Run `go run . upstream prepare`, `go test ./...` and `go run . preview all` from `tools/`.
4. Check desktop/mobile previews in English, Simplified Chinese and another official language; submit screenshots with the PR.
Contributions to themes, tooling, tests, documentation and translations are welcome. This guide covers the current source architecture; installation and release selection are described in the [README](README.md#installation).
Theme names use lowercase letters, digits and hyphens, starting with a letter. Themes contain only `theme.json` and `theme.css`. New themes default to `framed` with the `standard` layout; `layout` selects a structural preset from the shared framework. The optional `shared` mode remains CSS-only and does not add framework controls.
## Local Development
Shared header, action button, fallback URL, sidebar and footer controls live in `framework/mail/base/`. Structural presets live in `framework/layouts/`; they are framework code, not theme-owned mail templates. `tools/builder/framework.go` is the single alignment layer for official primary-action values and translations. Notification branches, subjects, attachments and contextual links come from downloaded official templates. Do not copy business logic into a theme.
## Design Guidelines
- Theme sources define presentation only; the shared framework organizes official mail values and translations into reusable controls.
- Use email-compatible CSS in theme sources and presentation markup in the framework. Theme CSS cannot load external resources, generate text or hide official content; the framework's instance-hosted logo is an intentional exception to external-image avoidance.
- The fragment validator permits tables, table rows/cells, divs and spans with presentation attributes. Review desktop and 390px mobile layouts.
- Test Gmail, Outlook and Apple Mail where available. Browser preview does not simulate every mail client's CSS support.
- Preserve the original theme's colors, fonts, borders, header treatment, button/fallback controls and layout. Do not replace established designs with generic cards or invented decorations.
- Gallery screenshots must be PNG, at most 50 KiB each; 10–20 KiB is preferred. Capture the current source build with the floating inspector closed.
## Official Snapshot Updates
Only the tool-generated `gitea.lock.json` is committed: stable Gitea 28+ tag, immutable commit and file checksums. Official templates, locale JSON files, favicon, license and adapter reference sources are downloaded to ignored `build/upstream/`. Do not maintain copies in the source repository.
### Command Reference
Run the following commands from `tools/`. All three subcommands accept `--root <repository-root>` (default: `..`, relative to the working directory); place this flag after the subcommand. Paths containing spaces must be quoted.
```powershell
# From tools/, with an explicit repository root:
go run . upstream verify --root "D:\Work\Development\WebSites\GiteaMailTemplates"
```
| Command | Purpose | Network and writes |
|---|---|---|
| `go run . upstream prepare` | Read the repository lock and prepare its exact inputs | If no cache exists, download files by locked commit, validate SHA-256 and create `build/upstream/`; otherwise verify the existing cache offline. Never changes the root lock. |
| `go run . upstream verify` | Audit the existing cache against the root lock | Offline, read-only; does not download files. Reports `[PASS]` and non-English missing-key `[FALLBACK]` lists. |
| `go run . upstream sync --tag vX.Y.Z` | Explicitly select an upstream version | Resolve the tag through the GitHub API, download by resolved commit and validate the snapshot; replace the cache and generate `gitea.lock.json`. Requires a stable `vX.Y.Z` tag with major version 28 or later. |
There is no implicit `latest`, local Gitea checkout input, token flag or authentication environment-variable support in these commands. Downloads use `api.github.com` (`sync`) and `raw.githubusercontent.com` (`sync`/first `prepare`); network errors and API rate limits are failures, not permission to change versions. Go may separately need network access for its toolchain/modules, even when snapshot verification itself is offline.
### Existing Clone and Offline Use
Use **Go 1.24 or later**. From the repository root, prepare the dependencies and locked official inputs, then run the checks and generate the preview:
```bash
cd tools
go mod download
go run . upstream prepare
go run . upstream verify
go test ./...
go run . preview all
```
`build all`, `preview all` and `dev` invoke preparation automatically. They still require the root lock. A complete verified cache and already installed Go dependencies/toolchain allow offline builds. `verify` checks official inputs, adapter reference hashes and official English keys; framework-added keys/action anchors are checked by build and rendering, so `verify` alone is not a compatibility certification.
Open `preview/index.html` in a browser, or run `go run . dev` from `tools/` and visit [http://127.0.0.1:3456](http://127.0.0.1:3456) for live reload. The development server watches themes, the framework, the lock/cache and preview fixtures.
The CLI uses urfave/cli and the x/net HTML parser. Python 3.11 or later is used by the documentation and packaging checks. Node.js and the dependencies in `tools/qa` are needed only for browser QA.
### Common Commands
Run these commands from `tools/`. Place flags before positional arguments.
| Command | Result |
|---|---|
| `go run . list` | List available themes |
| `go run . create my-theme` | Create theme metadata and CSS |
| `go run . build my-theme` | Generate one theme's installable templates |
| `go run . build all` | Generate every theme |
| `go run . preview all` | Build every theme and render all official languages |
| `go run . dev` | Start the development server on port 3456 |
| `go run . dev --port 3457` | Use a different local port |
| `go run . delete my-theme` | Remove the named theme's source directory |
`build` writes to `build/themes/<name>/mail/` and records file and source hashes in `build.json`. `preview` also builds the templates, then writes `preview/rendered.js` and `preview/rendered/<locale>.js`. These generated files and the downloaded inputs are ignored by Git. Keep them out of contributions.
## Adding a Theme
1. Run `go run . create my-theme` from `tools/`.
2. Edit `themes/my-theme/theme.json` and `theme.css`.
3. Run `go test ./...` and `go run . preview all` from `tools/`.
4. Check desktop and mobile layouts in English, Simplified Chinese and at least one other official language. Include screenshots with the pull request.
Theme names start with a lowercase letter and may contain lowercase letters, digits and hyphens. A theme directory contains only `theme.json` and `theme.css`.
```json
{
"name": "my-theme",
"description": "A short description of the theme",
"mode": "framed",
"layout": "standard"
}
```
| Mode | Generated presentation |
|---|---|
| `framed` | Shared controls and a framework layout, styled with the theme's CSS. New themes use this mode with the `standard` layout. |
| `shared` | CSS in the official head partial and the official footer partial; no additional framework controls or per-mail overrides. |
### Shared Framework
Headers, action buttons, fallback links, sidebars and footers live in `framework/mail/base/`. Layout presets live in `framework/layouts/`; the optional `layout` field selects a preset for framed themes. Colors, fonts and spacing belong in theme CSS.
`tools/builder/framework.go` adapts official action values and translation keys for the shared controls. Official templates retain responsibility for notification conditions, subjects, attachments and contextual links. Changes to controls or layout structure belong in the framework so all themes use the same adaptation logic.
Layout fragments must form balanced presentation markup. `__HEADER__` inserts the shared header, `__MAIL_TYPE__` expands to the discovered mail ID, and `__SIDEBAR__` inserts the shared sidebar in footer fragments. Deployment logos use `{{AppUrl}}assets/img/favicon.png`; generated preview data embeds the downloaded icon for offline display.
## Design Guidelines
- Use email-compatible CSS. Theme CSS must not load external resources, generate text or hide official content.
- Use presentation markup for layout fragments. The validator accepts `table`, `tbody`, `tr`, `td`, `div` and `span` with supported presentation attributes.
- When editing an existing theme, preserve its visual identity: palette, typography, borders, header, buttons and layout.
- Check desktop and 390px mobile previews, including long text and URLs. Test Gmail, Outlook and Apple Mail where available; the browser preview does not emulate mail clients.
- Keep gallery images in PNG format, at most 50 KiB each; 10–20 KiB is preferred. Follow the [capture guide](docs/images/README.md) for consistent images.
## Official Snapshot Updates
`gitea.lock.json` records a stable Gitea 28+ tag, its commit and per-file SHA-256 hashes. Official mail templates, locale catalogs, the favicon, license and reviewed adapter references are downloaded into `build/upstream/`. Only the generated root lock is committed; official files are not maintained in the source tree.
### Command Reference
Run from `tools/`. Each upstream subcommand accepts `--root <repository-root>`, defaulting to `..` relative to the working directory. Place the flag after the subcommand and quote paths containing spaces:
```powershell
go run . upstream verify --root "C:\Projects\GiteaMailTemplates"
```
| Command | Behavior |
|---|---|
| `go run . upstream prepare` | Read the root lock. Download and validate its exact inputs if the cache is absent; otherwise verify the existing cache offline. Leaves the root lock unchanged. |
| `go run . upstream verify` | Check the existing cache against the root lock, offline and read-only. Reports `[PASS]` and lists non-English missing keys as `[FALLBACK]`. |
| `go run . upstream sync --tag vX.Y.Z` | Resolve an explicit stable Gitea 28+ tag through the GitHub API, download and validate its files, then replace the cache and generate the root lock. |
`sync` uses `api.github.com`; file downloads use `raw.githubusercontent.com`. These commands do not accept a local Gitea checkout, authentication tokens or an implicit `latest` version. Network errors and API rate limits stop the operation. Go may separately need network access to download its toolchain or modules.
### Existing Clone and Offline Use
`build`, `preview` and `dev` prepare inputs automatically. They require the committed root lock and validate cached files before use. Once the cache, Go toolchain and dependencies are available, builds can run offline.
Use `upstream verify` to check the cache independently. It validates official file hashes, reviewed adapter references and official template keys in the English catalog. Build and rendering checks also cover framework translation keys and primary-action anchors, so cache verification is only one part of compatibility testing.
### Missing Lock and Explicit Version Updates
If `gitea.lock.json` is missing, `prepare`, `verify`, build and preview fail when opening it—even if `build/upstream/lock.json` remains. The cache lock is not a substitute. Restore the tracked root lock for a normal clone. For intentional initialization, `sync` does not require a prior root lock:
For an existing clone, restore the tracked `gitea.lock.json` if it is missing. The copy at `build/upstream/lock.json` cannot replace it. When intentionally initializing the lock, run:
```bash
cd tools
# Current source baseline; explicit initialization, not a release operation:
go run . upstream sync --tag v28.0.0
go run . upstream verify
go test ./...
go run . preview all
```
To review another version, replace the tag explicitly (for example, `v28.1.0`, still [PENDING] here). Review the generated lock diff, align the shared framework and fixtures, run all checks and the matching-instance smoke test, then update compatibility documentation. `sync` does not build themes, update Markdown, create Git tags, commit, push or publish a release. It must not be run merely to fix a missing cache.
To review a different version, specify its tag explicitly. Review the lock diff, update the framework adapter and fixtures as needed, and complete the checks and matching-instance smoke test before updating compatibility records. `sync` changes the cache and lock only; documentation and release publication are separate steps. Use `prepare` for a missing cache.
Changed translation or mail-renderer reference hashes block synchronization until the Go adapter is reviewed; downloading a newer version is not enough to approve it. Official English must contain all official template keys; builds additionally validate framework keys. Other languages fall back to English. Validation/network failures before cache replacement leave existing inputs unchanged. Cache replacement and writing the root lock are separate operations: if a filesystem failure leaves them inconsistent, subsequent verification fails; inspect both before retrying.
Changes to the reviewed translation or mail-renderer sources require an adapter review before their reference hashes can be updated. Official English must contain all referenced keys; other languages use English fallback. New mail types require framework alignment and fixtures in `tools/data/templates_config.json`, which supplies preview metadata and example contexts. Keep integer values as integers in JSON fixtures for Go formatting.
Network or validation failures before cache replacement leave existing inputs unchanged. Cache replacement and root-lock writing are separate operations; if a filesystem error interrupts them, inspect both before retrying.
### Cache Recovery
`prepare` refuses corrupt, incomplete or lock-mismatched caches; it does not merge or silently repair them. `sync` also refuses to replace a non-empty invalid snapshot. After inspecting the error, preserve the exact generated cache directory by moving it aside, then run `prepare` using the reviewed root lock. For example, in PowerShell **from the repository root**, choose an unused backup name:
`prepare` reports corrupt, incomplete or lock-mismatched caches without repairing them. `sync` also refuses to replace a non-empty invalid snapshot. Inspect the error and move the generated cache aside before preparing it again from the reviewed root lock.
For example, in PowerShell **from the repository root**, with an unused backup name:
```powershell
Move-Item -LiteralPath .\build\upstream -Destination .\build\upstream.backup
@@ -82,58 +133,87 @@ go run . upstream prepare
go run . upstream verify
```
Do not remove the whole `build/` directory or edit cached official files. To restore a previous version after a deliberate sync, restore its reviewed root lock and rebuild the cache in the same way. Avoid simultaneous `sync`/`prepare`/build processes against one cache; stop `dev` while replacing inputs.
Preserve the rest of `build/` and leave official cached files unedited. To return to a previous snapshot, restore its reviewed root lock and rebuild the cache in the same way. Stop `dev` before replacing inputs, and avoid concurrent processes writing to the same cache.
Mail types are discovered from the snapshot. `tools/data/templates_config.json` supplies names, descriptions and mock contexts only. A new official mail type requires a fixture before preview can pass.
### Known Upstream Formatting Issue
Gitea v28.0.0 has a reviewed Polish `mail.team_invite.text_1` placeholder defect. Preview preserves official behavior and reports `[UPSTREAM-WARN]`; the exception matches the exact official text. Other formatting errors fail rendering. Do not edit locale snapshots to conceal upstream defects.
## Local Development
Use **Go 1.24+**. The CLI uses urfave/cli; HTML validation uses Go's x/net HTML parser. Run `go mod download` and `upstream prepare` once; subsequent verified builds work offline.
```bash
cd tools
go run . list
go run . build all
go run . preview all
go run . dev
# http://127.0.0.1:3456
```
`build` writes installable files to `build/themes/<name>/mail/`. `preview` also builds them, then writes a small manifest and one JS bundle per official language. Open `preview/index.html` directly for static preview; its language loader supports `file://`.
The loopback development server watches theme CSS/metadata, shared framework, lock/cache and fixtures. It rebuilds in-process and sends SSE reloads. Installable logos reference `{{AppUrl}}assets/img/favicon.png`; only the generated static preview embeds the downloaded official icon for offline display.
Gitea v28.0.0 contains a Polish `mail.team_invite.text_1` placeholder defect. Preview preserves the official output and reports `[UPSTREAM-WARN]`. The exception matches the exact reviewed source text; other formatting errors fail rendering. Report upstream defects without modifying the cached locale files.
## Verification and Release
Tests check deterministic framework adaptation and generation, fail-closed action anchors, official keys and preserved notification semantics. Rendering tests cover all themes/languages and push, review, reply, workflow and attachment branches. Shared controls/branding are explicit presentation additions; button labels, fallback targets and logo references are validated separately.
### Checks for a Pull Request
Before a release, use an isolated Gitea instance matching the locked tag and trigger a real password-reset or notification email. The administration test-email button bypasses custom templates. Confirm template loading and capture the rendered mail without sending to real users.
From `tools/`, run `go test ./...` and `go run . preview all`. Tests cover deterministic generation, changes to action anchors, translation keys, and notification subjects, text and links across all themes and languages. Fixtures include push, review, reply, workflow and attachment branches. Shared controls and branding are accounted for separately from official notification content.
The optional `tools/integration` test automates this with disposable SQLite, users, Git/SSH paths and loopback SMTP. Set `GITEA_SMOKE_BINARY` to a checksum-verified official binary of the locked version, then run `go test ./integration -v -count=1` from `tools/`. Optional browser QA lives in `tools/qa`: install its dependencies, then run `npm test` after generating preview data; `PREVIEW_DEV_URL` includes HTTP preview checks and `--update-gallery` refreshes screenshots.
For documentation, tracker or packaging changes, run from the repository root:
Release tags must match the snapshot's Gitea version. Add reviewed notes at `.github/release-notes/vX.Y.Z.md`. The workflow verifies the lock and tests, packages generated themes, multilingual preview, documentation and upstream license/provenance, then updates marked release labels. Keep source-only work separate from the published compatibility matrix. Existing historical tags and assets are unchanged.
```bash
python -B -m unittest discover -s .github/scripts -p 'test_*.py'
```
From the repository root, run `python .github/scripts/package_release.py --version vX.Y.Z --output <new-output-directory>` after `preview all` for manual packaging. The same script is used by the release workflow. It verifies source/generated hashes and all language bundles, excludes undeclared stale build directories, and refuses to overwrite existing archives.
Keep English and Simplified Chinese guides aligned when changing shared instructions. Include a description of the change, relevant checks and screenshots for visual changes in the pull request.
### Browser and Gitea Checks
After generating preview data, run the optional browser suite:
```bash
cd tools/qa
npm install
npx playwright install chromium
npm test
```
To use installed Chrome or Edge, set `BROWSER_EXECUTABLE_PATH` instead of installing Chromium. Set `PREVIEW_DEV_URL` to include a running HTTP preview in the checks. `npm test -- --update-gallery` also refreshes gallery screenshots.
Before a release, test generated overrides in an isolated Gitea instance matching the locked version and capture a real password-reset or notification email. The administration test-email button bypasses custom templates.
The optional `tools/integration` test uses disposable SQLite data, users, Git/SSH paths and loopback SMTP. Set `GITEA_SMOKE_BINARY` to a checksum-verified official binary matching the lock, then run `go test ./integration -v -count=1` from `tools/`. It captures mail locally without sending to real users. Without this variable, the test is skipped. The release workflow does not run the optional browser or real-Gitea checks automatically.
### Preparing a Release
Release tags must match the locked Gitea version. The current source refactor is unreleased; retain existing v28.0.0 and historical assets.
1. Complete automated checks, preview review and the matching-instance smoke test.
2. Add reviewed notes at `.github/release-notes/vX.Y.Z.md` and update compatibility records with the verification results.
3. Generate all themes and language bundles with `go run . preview all` from `tools/`.
4. Package the release and verify its contents before publication.
For manual packaging, run from the repository root:
```bash
python .github/scripts/package_release.py --version vX.Y.Z --output <new-output-directory>
```
Replace the version and output placeholder with the reviewed tag and a new directory. The script checks source and generated hashes, includes all language bundles, excludes stale theme builds, and refuses to overwrite existing archives.
The release workflow uses the same script to package templates, previews, documentation, the upstream license and provenance. It also updates managed release labels. Confirm Actions support and write permissions on the configured Gitea host before relying on automated publication. See [version tracking](COMPATIBILITY.md#version-tracking) for the managed Markdown blocks.
### Gitea Workflow Configuration
Both workflows use the `linux-amd64-docker-small` runner label. The job image must support the Node.js actions used for checkout and toolchain setup, as well as Git and a POSIX shell. Go and Python are installed by the setup steps.
PR creation and release uploads use `.github/scripts/gitea_actions.py` and the instance's `/api/v1` API. The workflows pass the instance URL, repository and built-in `GITEA_TOKEN`; repository settings must allow the requested code, release and pull-request writes. The optional `UPSTREAM_GITHUB_TOKEN` secret is used only to query official releases on GitHub. Without it, those queries use GitHub's unauthenticated API limit.
The tracker reuses an existing branch when its content matches and reuses an open PR for that branch. A differing branch requires manual review; the workflow does not force-push. Release publication refuses any existing release, including a draft. New releases remain drafts until both archives upload successfully. If an upload fails, inspect the draft before retrying; published releases and assets must remain unchanged.
## Reporting Problems
Include the snapshot tag/commit, theme, email type, preview language and error. Run `go run . upstream verify` and `go run . preview all` first; attach screenshots or the relevant render diagnostic.
Include the Gitea version, template release or source commit, theme, mail type, language and steps to reproduce. For source-build problems, include the snapshot tag/commit and output from `go run . upstream verify` or `go run . preview all`. For display problems, include the mail client and a screenshot with personal data removed.
## Commit Conventions
- `style(<name>):` — theme presentation
- `preview:` — browser preview
- `tools:` — CLI/build/snapshot tooling
- `docs:` — documentation and translations
- `fix:` — bug fixes
- `refactor:` — restructuring
- `chore:` — maintenance
| Prefix | Scope |
|---|---|
| `style(<name>):` | Theme presentation |
| `preview:` | Browser preview |
| `tools:` | CLI, build and snapshot tools |
| `docs:` | Documentation and translations |
| `fix:` | Bug fixes |
| `project:` | Repository configuration and project structure |
| `refactor:` | Code restructuring |
| `chore:` | Maintenance |
## Translations and License
- English (this document)
- [简体中文](docs/CONTRIBUTING.zh-CN.md)
Contributions are licensed under MIT. Retain Gitea copyright and the upstream license when distributing derived templates.
The [Simplified Chinese guide](docs/CONTRIBUTING.zh-CN.md) covers the same workflow. Contributions are licensed under MIT. Retain Gitea copyright and the upstream license when distributing derived templates; see [third-party notices](THIRD_PARTY_NOTICES.md).