220 lines
14 KiB
Markdown
220 lines
14 KiB
Markdown
# Contributing to Gitea Mail Templates
|
||
|
||
[简体中文](docs/CONTRIBUTING.zh-CN.md) · [Project overview](README.md) · [Compatibility](COMPATIBILITY.md)
|
||
|
||
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).
|
||
|
||
## Local Development
|
||
|
||
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 test ./...
|
||
go run . preview all
|
||
```
|
||
|
||
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
|
||
|
||
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
|
||
go run . upstream sync --tag v28.0.0
|
||
go run . upstream verify
|
||
go test ./...
|
||
go run . preview all
|
||
```
|
||
|
||
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.
|
||
|
||
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` 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
|
||
Set-Location tools
|
||
go run . upstream prepare
|
||
go run . upstream verify
|
||
```
|
||
|
||
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.
|
||
|
||
### Known Upstream Formatting Issue
|
||
|
||
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
|
||
|
||
### Checks for a Pull Request
|
||
|
||
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.
|
||
|
||
For documentation, tracker or packaging changes, run from the repository root:
|
||
|
||
```bash
|
||
python -B -m unittest discover -s .github/scripts -p 'test_*.py'
|
||
```
|
||
|
||
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 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
|
||
|
||
| 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
|
||
|
||
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).
|