chore: migrate mail themes to shared framework and locked upstream inputs
This commit is contained in:
KenanZhu committed
1 parent
5c0589f6f6
commit
fec3ace600
225 files changed
+4718
-15807
No files matched your search
@@ -3,102 +3,70 @@
|
||||
|
||||
## Project Overview
|
||||
|
||||
A growing collection of email template themes for self-hosted Gitea instances. Each theme contains 11 Go `html/template` files covering all supported Gitea notification email types.
|
||||
Theme presentation for self-hosted Gitea, driven by locked official inputs and a reusable control framework. New source architecture supports Gitea 28+; historical release tags retain their original layouts and compatibility.
|
||||
|
||||
## Repository Layout
|
||||
|
||||
```
|
||||
themes/ # One directory per theme, with 11 .tmpl files each
|
||||
aurora/ # Ethereal / Dreamlike
|
||||
bloom/ # Creative / Startup (glassmorphism)
|
||||
ember/ # Community / Open Source
|
||||
heritage/ # Education / Research
|
||||
horizon/ # Enterprise / Corporate
|
||||
ink/ # Editorial / Publishing
|
||||
mono/ # Minimal / Swiss design
|
||||
neon/ # Cyberpunk / Gaming
|
||||
terminal/ # Developers / Tech
|
||||
terra/ # Nature / Sustainability
|
||||
.../ # Additional themes can be added
|
||||
tools/ # Go CLI tooling (modular; uses urfave/cli/v2)
|
||||
tools.go # Main entry point
|
||||
cli/ # CLI subcommands: list, create, delete, preview
|
||||
config/ # Config types and templates_config.json loading
|
||||
data/ # templates_config.json — single source of truth for template metadata
|
||||
preview/ # Template rendering engine (funcs, locale, engine)
|
||||
go.mod # Go module (CLI dependency declared here)
|
||||
preview/ # Browser-based live preview
|
||||
index.html # SPA with style/template/client/viewport switching
|
||||
rendered.js # Pre-rendered HTML (generated, ignored in source clones)
|
||||
docs/ # Bilingual documentation (English + Simplified Chinese)
|
||||
gitea.lock.json # Generated official version, commit and file SHA-256; no vendored upstream source
|
||||
framework/ # Shared header/action/fallback/footer controls and structural layout presets
|
||||
themes/<name>/ # theme.json and theme.css only; no mail data/logic/translation definitions
|
||||
tools/ # Go 1.24+ CLI; urfave/cli and x/net HTML validation
|
||||
upstream/ # Explicit sync, checksum/adapter verification and key discovery
|
||||
builder/ # One official-context alignment layer and theme package generation
|
||||
config/, data/ # Names, descriptions and mock contexts; not a template inventory
|
||||
preview/ # Official-compatible rendering, locale adapter and SSE dev server
|
||||
cli/ # list, create, delete, build, preview, dev, upstream
|
||||
build/themes/ # Generated installable overrides; ignored
|
||||
build/upstream/ # Downloaded immutable official mail/locales/assets/license; ignored
|
||||
preview/ # Vanilla JS UI, generated manifest and per-language scripts
|
||||
docs/ # English/Simplified Chinese documentation and gallery images
|
||||
```
|
||||
|
||||
## Working With Templates
|
||||
## Source and Theme Rules
|
||||
|
||||
### Template Files
|
||||
- Never commit or hand-maintain official input files. `upstream prepare` downloads missing inputs to the ignored cache. `upstream sync --tag vX.Y.Z` explicitly regenerates the lock after reviewing a new version.
|
||||
- Build/preview bootstrap a missing cache, then verify it offline against the lock's commit and per-file SHA-256. Corruption is an error, never silently repaired.
|
||||
- Root `gitea.lock.json` is mandatory for prepare/verify/build/preview/dev; a cached lock is not a substitute. Restore the tracked lock for normal clones; intentional initialization uses explicit `upstream sync --tag v28.0.0`. There is no automatic latest-version selection.
|
||||
- Run upstream commands from `tools/`, or provide the subcommand's `--root` (default `..`). `verify` is read-only; `prepare` never rewrites the root lock; `sync` requires network and stable 28+ tags, replaces cache/lock but does not change docs or publish. See CONTRIBUTING for recovery; preserve invalid caches before rebuilding and avoid concurrent cache writers.
|
||||
- Changed reviewed translation/mail-renderer references require an adapter review before updating reference hashes.
|
||||
- Official templates own notification data, conditions, subject sections and functional URLs. The shared framework may reorganize presentation and add controls using those values and official translations; themes may not add business logic.
|
||||
- `theme.json` has `name`, `description`, `mode` (`shared` or `framed`) and optional `layout`. New themes default to `framed` with the `standard` framework preset. `shared` remains a minimal CSS-only mode without framework controls.
|
||||
- All framed themes use the same header/action/fallback/footer partials and single adapter. Structural presets live in `framework/layouts/`, not in theme directories; color/font/spacing rules live in theme CSS.
|
||||
- Layout fragments form balanced presentation markup. `__HEADER__` inserts the shared brand control; `__MAIL_TYPE__` expands to the discovered mail ID. Deployment logos use `{{AppUrl}}assets/img/favicon.png`; the static preview uses the downloaded icon in its generated data only.
|
||||
- CSS must not add text, external resources or hide official content. Use literal email-compatible CSS; browser preview is not a mail-client emulator.
|
||||
- All referenced translation keys must exist in the official English catalog, including keys outside `mail.*`. Other languages use official English fallback.
|
||||
- The reviewed Polish v28.0.0 invitation placeholder defect is reported as `[UPSTREAM-WARN]`; its exact source text is preserved.
|
||||
- Mail entrypoints come from the snapshot; new types need fixtures. Keep JSON fixture integers as integers for Go formatting.
|
||||
|
||||
- All `.tmpl` files use Go `html/template` syntax
|
||||
- Must use only Gitea 28's built-in template functions: `AppUrl`, `DotEscape`, `QueryEscape`, `ShortSha`, `HTMLFormat`, `PathEscapeSegments`, `FormatByteSize`
|
||||
- Must use only official Gitea translation keys (`mail.*` namespace)
|
||||
- Never reference `.DisplayName` in templates where the data context lacks it (collaborator, transfer, release, workflow_run, assigned, default)
|
||||
- Each style must have all 11 template types
|
||||
## Development
|
||||
|
||||
### Adding a New Theme
|
||||
1. `cd tools && go run . create <name>`.
|
||||
2. Edit only theme metadata/CSS. Shared controls or layout presets are framework changes.
|
||||
3. Run `go run . upstream prepare`, `go test ./...` and `go run . preview all`.
|
||||
4. Check desktop/mobile layouts and languages; update the gallery if appropriate.
|
||||
|
||||
1. Scaffold the new theme: `cd tools && go run . create <name>` — creates the full directory structure with placeholder `.tmpl` files for all 11 email types
|
||||
2. Write all 11 `.tmpl` files with unique visual design
|
||||
3. Run `cd tools && go run . preview all` to regenerate preview data
|
||||
4. Update README.md style gallery table
|
||||
`build all` generates `build/themes/<name>/mail/`. `preview all` builds and renders every official language, writing `preview/rendered.js` and `preview/rendered/<locale>.js`. Static preview must work on `file://` via script loading. Keep generated output ignored.
|
||||
|
||||
### Preview System
|
||||
`dev` uses Go HTTP/SSE on loopback and watches theme resources, framework, lock/cache and fixture data. The preview remains vanilla JS with theme/template/language/view switching, desktop/mobile viewports, panel controls and keyboard navigation.
|
||||
|
||||
- `preview/index.html` loads `preview/rendered.js` (pre-rendered by Go) and displays in iframes
|
||||
- Supports theme/template switching, view mode (Modern/Source), and viewport toggle (Desktop 1386x780 / Mobile 390x780)
|
||||
- Keyboard navigation: `←→` cycles focus between Theme/Template/View selects, `↑↓` selects within the focused dropdown, `d`/`m` toggles viewport
|
||||
- `REGISTRY` and `PARAMS` are auto-generated from `templates_config.json` — no manual syncing needed
|
||||
- Static preview works via `file://` after running `go run . preview all` in a source clone; the updated packaging workflow includes generated preview data and screenshots for future builds (v28.0.0 and older archives include neither)
|
||||
- Dev server (`go run . dev`) — pure Go HTTP server with SSE live reload; watches `themes/` for `.tmpl` changes, re-renders in-process, and pushes reload events to the browser
|
||||
|
||||
### Build Tool
|
||||
|
||||
- `tools/tools.go` is the main entry point for the modular CLI
|
||||
- Subcommands: `list`, `create`, `delete`, `preview`, `dev`
|
||||
- Template metadata lives in `tools/data/templates_config.json` — the single source of truth
|
||||
- `tools/config/` handles config loading and data flattening
|
||||
- `tools/preview/` implements the rendering engine (template funcs, locale, engine, markSafeHTML)
|
||||
- `tools/cli/` implements CLI subcommands using `github.com/urfave/cli/v2`
|
||||
- `tools/preview/server.go` pure Go dev server with SSE live reload and in-process template re-rendering
|
||||
- Uses Go's native `html/template` package for template rendering
|
||||
Tests compare subjects, notification text and functional links across every language/theme and relevant branch, accounting explicitly for framework-added controls/branding. Verify button labels and identical button/fallback URLs separately. Before release, capture real mail using an isolated Gitea matching the locked version.
|
||||
|
||||
## Versioning
|
||||
|
||||
- Release tags identify actual downloadable packages; the compatibility matrix distinguishes released tags from source-only fixes
|
||||
<!-- RELEASE:CURRENT -->
|
||||
- Current template release: **v28.0.0**.
|
||||
<!-- /RELEASE:CURRENT -->
|
||||
- v28.0.0 was verified against Gitea 28.0.0. Gitea 28 replaces the mail-template `FileSize` function with `FormatByteSize`; earlier template releases can fail on Gitea 28, and v28.0.0 is not a drop-in replacement for earlier mail contexts. Choose an archive from the per-version matrix in `COMPATIBILITY.md`; v1.27.2 is a known partial fix for push notifications
|
||||
- The snapshot-driven source refactor is unreleased. Its baseline is Gitea v28.0.0; do not replace the existing v28.0.0 assets.
|
||||
- Historical compatibility is documented in `COMPATIBILITY.md`, including the incomplete v1.27.2 push fix. New source architecture does not extend support to earlier Gitea versions.
|
||||
<!-- TRACKER:UPSTREAM -->
|
||||
- Latest upstream Gitea release: 28.1.0 [PENDING].
|
||||
<!-- /TRACKER:UPSTREAM -->
|
||||
- When a new Gitea version appears, the tracker adds pending compatibility and history rows and updates marked version lines and the pending README badge. After verification, update that version's matrix row and README tested text/badge; keep unreleased fixes distinct from the published release
|
||||
- Tag a new release (`vX.Y.Z`) only when the template content itself changes. On the new Gitea host, do not assume tag pushes automatically build or upload archives; verify the Gitea workflow before relying on it
|
||||
- Before tagging, add `.github/release-notes/vX.Y.Z.md`, run `go test ./...` and `go run . preview all` from `tools/`. The release workflow packages the tag, publishes the reviewed notes, and then updates `RELEASE` blocks on `main` when the host supports those Actions and write permissions; otherwise build/upload and update the labels manually
|
||||
- Participating Markdown documents declare their blocks in a `DOC-TAGS` JSON comment. Each block uses a paired opening `<!-- SUBJECT:CONTENT -->` and closing `<!-- /SUBJECT:CONTENT -->` comment; its body is the managed text. `TRACKER` handles upstream-pending content, `RELEASE` handles published-template labels, and `TRACKER:LATEST-TESTED` / `TRACKER:LATEST-VERIFIED` are manual-only. Within a document, the first block for a subject/content pair wins
|
||||
- Upstream discovery only adds pending documentation; it must not implicitly update snapshots or mark versions verified.
|
||||
- Release tags match the locked Gitea version. Review notes in `.github/release-notes/vX.Y.Z.md`, test, build and complete the matching-instance smoke test before publication.
|
||||
- The workflow packages generated overrides, preview language bundles, docs and upstream license/provenance. Verify Actions/write permissions on the configured Gitea host before relying on automatic upload.
|
||||
- Markdown managed blocks declare pairs in `DOC-TAGS`. Opening `<!-- SUBJECT:CONTENT -->` and closing `<!-- /SUBJECT:CONTENT -->` delimit managed text; the first repeated pair wins. TRACKER manages pending upstream labels; RELEASE manages published labels. LATEST-TESTED and LATEST-VERIFIED remain manual-only.
|
||||
|
||||
## Commit Conventions
|
||||
|
||||
- `style(name):` — template changes for a specific theme
|
||||
- `preview:` — preview tooling changes
|
||||
- `tools:` — Go CLI/build tooling changes
|
||||
- `docs:` — documentation and translations
|
||||
- `fix:` — bug fixes
|
||||
- `project:` — README, LICENSE, AGENTS.md, meta
|
||||
- `refactor:` — code restructuring (e.g. modularization)
|
||||
- `chore:` — maintenance (config updates, build scripts)
|
||||
|
||||
## Constraints
|
||||
|
||||
- No JavaScript framework dependencies — preview is vanilla JS
|
||||
- The CLI uses `github.com/urfave/cli/v2`; the preview server itself uses Go's standard HTTP library
|
||||
- Templates must remain compatible with Gitea's `html/template` execution environment
|
||||
- Preview works with `file://` protocol (no server needed)
|
||||
Use `style(name):`, `preview:`, `tools:`, `docs:`, `fix:`, `project:`, `refactor:` or `chore:` as appropriate. Preserve unrelated user changes and keep generated files out of commits.
|
||||
Reference in new issue
Block a user