22 KiB
Contributing
Contributions to themes, tools, documentation and translations are welcome. This guide covers the development environment, command-line tools and contribution workflow. For template installation and release selection, see the README and compatibility matrix.
Local Development
Use Go 1.24 or later. From the repository root, prepare the dependencies and locked official files, run the tests and generate the preview:
cd tools
go mod download
go run . upstream prepare
go test ./...
go run . preview all
Then open preview/index.html in a browser, or run go run . dev for live preview. The validation and packaging workflows use Python 3.11.
The project is organized into a shared framework, theme styles and build tools. Official templates provide notification content, conditions, subjects and links. The shared framework handles presentation, while theme metadata and CSS select layouts and define styles. See the README for the directory layout.
Note
Downloaded official files, generated templates and preview data are not tracked in version control. Submit the relevant source files, tests and documentation; do not include
build/,dist/or generated preview data.
Development Tools
The CLI prepares official files, manages themes, builds templates and generates previews.
Tip
Run all commands below from
tools/. Place options before positional arguments. In the examples,my-themeis a theme name; quote paths containing spaces.
| Command | Purpose |
|---|---|
upstream |
Prepare, synchronize or verify locked official build inputs |
build |
Generate installable themes from official inputs and shared controls |
list |
List available themes and their metadata |
create |
Create theme CSS and metadata for the shared framework |
delete |
Delete one or more theme source directories |
preview |
Pre-render mail templates to generate preview and test data |
dev |
Start a live-reload development server with SSE browser refresh |
help, h |
Show the command list or help for a specific command |
upstream
upstream manages the official files pinned by gitea.lock.json, including mail templates, locale files, the icon, license and reviewed adapter reference sources. Downloaded files are stored in build/upstream/.
| Subcommand | Behavior |
|---|---|
prepare |
Read the root lock file. Download and verify inputs if the cache is absent, or verify an existing cache before use. Does not modify the root lock file. |
sync --tag <TAG> |
Download the specified stable version's official files, verify them, then replace the cache and update the root lock file. |
verify |
Verify the existing cache against the root lock file, offline and read-only. |
To prepare inputs for the first time or check them independently, run:
go run . upstream prepare
go run . upstream verify
All three subcommands support --root, which defaults to .. relative to the current working directory. For example:
go run . upstream verify --root "C:\Projects\GiteaMailTemplates"
The root lock file records the Gitea tag, its commit and file SHA-256 hashes. verify checks file hashes, reviewed adapter reference sources and English translation keys referenced by official templates. Missing keys in other languages produce warnings and fall back to English in the preview. Building and rendering also check framework translation keys and action-link anchors; cache verification does not replace those checks.
Updating the Official Version
Use sync only when reviewing a new official version. For example, to explicitly synchronize to v28.0.0:
go run . upstream sync --tag v28.0.0
go run . upstream verify
go test ./...
go run . preview all
Tags must use the vX.Y.Z format and identify a stable release of Gitea 28 or later. latest, prerelease tags and older version tags are not supported. sync resolves tags through api.github.com and downloads files from raw.githubusercontent.com; it does not accept a local Gitea clone or an authentication token option.
After synchronization, review the lock file diff, adjust adapter logic and preview data as needed, and update compatibility records after validation. Synchronization does not automatically update documentation, release tags or compatibility conclusions.
Important
When adapter reference sources change, review the affected behavior before updating their hashes. Do not change hashes simply to bypass the checks.
Network or validation errors before cache replacement leave existing files unchanged. Cache replacement and root lock file writing are separate operations; if a filesystem error interrupts the process, check that both agree before retrying. Stop dev before updating inputs to avoid concurrent processes writing to the cache.
build
build generates installable mail templates from locked official files, the shared framework and theme sources. Specify one or more themes, or use all to build every theme:
go run . build aurora
go run . build aurora bloom
go run . build all
| Option | Default | Description |
|---|---|---|
--folder |
../themes |
Theme source directory; its parent is used as the project root |
When using another project path, that project's root must also provide the lock file and shared framework:
go run . build --folder "C:\Projects\GiteaMailTemplates\themes" aurora
Output is written to build/themes/<name>/mail/, with build provenance and generated file hashes recorded in the adjacent build.json. Rebuilding updates the selected themes and removes their obsolete templates; it does not clean unselected themes. Building does not deploy templates. See the README for installation.
Tip
To change templates, edit theme sources, the shared framework or build adapter logic. Direct edits to generated
.tmplfiles are overwritten by subsequent builds and cause packaging provenance checks to fail.
list
list displays theme names, modes and short descriptions, sorted by name:
go run . list
Use --folder to select a theme directory; the default is ../themes. The command validates theme metadata and styles without downloading official files or generating templates. Fix any reported theme-format errors first.
create
create creates theme.json and theme.css for a new theme and supports creating multiple themes at once:
go run . create my-theme
go run . create first-theme second-theme
Use --folder to select the theme source directory; the default is ../themes. The command does not overwrite existing directories. Theme names start with a lowercase letter and contain only lowercase letters, digits and hyphens. Avoid all, because build and preview commands treat it as the selector for every theme.
Edit the generated metadata and CSS to describe and style the theme. For example:
{
"name": "my-theme",
"description": "A short description of the theme",
"mode": "framed",
"layout": "standard"
}
name must match the directory name. Theme directories contain only these two source files, without copies of official mail templates or translations.
| Mode | Presentation structure |
|---|---|
framed |
Shared controls and a layout, styled with theme CSS. New themes default to this mode and the standard layout. |
shared |
CSS is added to the official head partial, and the official footer partial is retained. No framework controls or per-mail template overrides are added. |
A framed theme can use layout to select a preset from framework/layouts/. Headers, action buttons, fallback links, sidebars and footers live in framework/mail/base/. Structural changes shared by multiple themes belong in the framework; adaptation between official content and controls is handled in tools/builder/framework.go.
Theme CSS uses existing classes such as email-heading, email-text and email-subtext to distinguish headings, body text and supporting text. Preserve official notification wording, translation keys, variables and functional links. Do not generate wording or hide notification content through CSS. The style validator rejects template expressions, external resource references and unsupported hiding rules.
After completing the theme, run the tests and generate a preview:
go test ./...
go run . preview my-theme
delete
delete removes the source directories of one or more named themes:
go run . delete my-theme
go run . delete first-theme second-theme
Use --folder to select the theme directory; the default is ../themes.
Warning
After validation, the command deletes directories directly, without a confirmation prompt or recovery through the recycle bin. Check the names and preserve any changes you need before running it.
Missing themes produce warnings; invalid themes and symlink directories are rejected. Themes are processed sequentially, so a later failure does not restore directories already deleted. all does not mean deleting every theme.
Deleting sources does not remove previously generated builds, preview data or deployed templates. Run preview all again to update the preview manifest. Remove deployed templates separately at their actual installation location.
preview
preview builds the selected themes and renders all locked official languages using sample data. Specify one or more themes, or use all:
go run . preview aurora
go run . preview aurora bloom
go run . preview all
| Option | Default | Description |
|---|---|---|
--folder |
../themes |
Theme source directory; its parent is used as the project root |
--config |
./data/templates_config.json |
Mail type descriptions and preview sample data |
--output |
preview/rendered.js under the project root |
Preview manifest path |
Default output includes preview/rendered.js and preview/rendered/<locale>.js. Open preview/index.html in a browser; no server is required. See the README for controls and shortcuts.
Important
Each run overwrites the preview manifest at the output location instead of merging with previously selected themes. For example, after
preview aurora, the manifest contains only Aurora. Runpreview allto restore every theme.
To use a custom output path:
go run . preview --config ./data/templates_config.json --output ../build/preview-review/rendered.js all
Note
Language data is written to a
rendered/directory next to the output file. The command does not copy the preview interface or change its script references; the existingpreview/index.htmlstill reads data from the default location.
When adding mail types or rendering branches, extend the descriptions and sample contexts in tools/data/templates_config.json. Keep integer values, such as counts and sizes, as integers in JSON. Use controlled test content for HTML fields such as body text, release notes and review content; do not include personal information or real credentials.
Note
The preview checks template structure and presentation using sample contexts. It does not replace parameter compatibility review for the target Gitea version. Browsers and mail clients also differ in their CSS support.
dev
dev starts a local development server, building every theme and preparing preview data on startup:
go run . dev
Open http://127.0.0.1:3456. The default port is 3456; use --port to change it:
go run . dev --port 3457
The server listens only on 127.0.0.1. Press Ctrl + C in the terminal to stop it. The command locates the project relative to the current tools/ working directory and does not provide --folder, --config or --root options.
The server watches theme sources, the shared framework, the root lock file, official cache and preview data in tools/data/. Changes trigger a rebuild and refresh the preview through server-sent events (SSE). If a build fails, resolve the terminal error and save the file again.
Tip
Refresh the page manually after editing
preview/index.html. Stop and restart the server after editing Go tool code. These files are outside the current automatic rebuild watch scope.
help, h
View all commands or help for a specific command:
go run . help
go run . h
go run . help build
go run . preview --help
For upstream subcommand options, place --help after the subcommand:
go run . upstream prepare --help
go run . upstream sync --help
go run . upstream verify --help
Tool diagnostics use the [LEVEL] [NAME] Message format. [I], [W], [E] and [F] mean information, warning, error and fatal error, respectively. Level markers use different colors in supported terminals; set NO_COLOR to disable colors. Failed commands return a nonzero exit code. Preserve the complete output when troubleshooting.
Frequently Asked Questions
What if the lock file or official cache is missing?
If an existing clone lacks gitea.lock.json, restore the tracked root lock file. The copy at build/upstream/lock.json cannot replace it. If only the cache is missing, run upstream prepare rather than synchronizing to another version to recover it. build, preview and dev prepare official inputs automatically. They can run offline once the cache, Go toolchain and dependencies are available; upstream verify always checks local files only. For network errors or GitHub API rate limits during the initial download, resolve the network issue and retry.
What if the cache is corrupt or does not match the lock file?
prepare does not repair corrupt caches automatically, and sync refuses to replace a non-empty invalid snapshot. Stop the development server, preserve the root lock file and move the cache to a backup location before preparing it again. For example, in PowerShell from the repository root, use a backup name that does not already exist:
Move-Item -LiteralPath .\build\upstream -Destination .\build\upstream.backup
Set-Location tools
go run . upstream prepare
go run . upstream verify
Warning
Do not edit official cached files directly or delete the rest of
build/. To revert the official version, restore the previously reviewed root lock file and rebuild the cache in the same way.
Why does synchronizing a new version report changed adapter sources?
The project pins reviewed mail-rendering and translation reference sources. When upstream changes these implementations, the tool requires another review to avoid using incompatible preview functions or variable structures. Examine the official changes, adjust adapter logic and relevant tests, then update the reference hashes. New mail types, translation keys, functions or variable paths may also require changes. Update compatibility records after validation; a successful download does not establish compatibility.
Why do some languages use English or produce formatting warnings?
Official English must contain all referenced translation keys. Missing keys in other languages fall back to English and produce warnings. Preserve official locale files without adding translations to the cache.
For example, Gitea v28.0.0 has a known placeholder defect in the Polish mail.team_invite.text_1. The preview preserves official output for the exact reviewed source text and reports a warning. This exception does not apply to other formatting errors. Include the version, translation key and reproduction details when reporting new issues for review and upstream feedback.
Why does the preview not show a new theme or recent changes?
The static preview does not build automatically. Run preview all again and refresh the page, then confirm that the manifest contains the required themes. With a custom output path, check where the preview interface actually reads its data. With dev, first check the terminal for rebuild errors. Go code changes require a server restart; preview interface changes require a manual refresh. If the default port is occupied, select another port with --port.
Does a successful build mean all Gitea versions are supported?
Builds target the official inputs specified in the root lock file. Other versions may change template directories, functions or variable structures, so a successful build or preview alone cannot establish backward compatibility. Select release archives using the compatibility matrix, rather than installing new-version templates directly on older instances.
Why does the packaging script reject the current output?
Run preview all before packaging to ensure that every theme and language bundle is present and generated files match the current sources. The version argument must match the tag in the root lock file. Rebuild and regenerate previews after source or generated file changes. The script does not overwrite existing release archives. Use a new output directory when repackaging and retain old artifacts needed for comparison.
Other Contribution Information
Themes and the Shared Framework
Use CSS suitable for mail clients. When editing an existing theme, preserve its palette, fonts, borders and layout, keep headings, body text and supporting text distinct, and account for long text, long URLs and mobile widths. Layout fragments use presentation markup and support table, tbody, tr, td, div, span and attributes allowed by the validator. Combined markup must have balanced tags. __HEADER__ inserts the shared header, __MAIL_TYPE__ expands to the mail ID, and __SIDEBAR__ inserts the shared sidebar in footer fragments. Review changes to notification variables and conditions in the build adapter logic, not in theme CSS or layout presets.
For new themes, update the galleries in both English and Chinese READMEs. Use PNG images of at most 50 KiB each; 10–20 KiB is preferred. Follow the capture guide for consistent themes, mail types, languages and cropping.
Commits and Pull Requests
Keep changes focused on a specific problem and avoid unrelated formatting changes. Describe the reason, scope and validation results in the pull request. For visual changes, you can include comparison images generated with sample data. When changing themes, the shared framework or Go tools, run from tools/:
go test ./...
go run . preview all
For changes to mail content, links, variables or function adaptation, add regression tests covering affected conditional branches. Existing tests check generated output, translation keys, notification subjects, text and links across every theme and language, including push, review, reply, workflow and attachment branches.
When changing packaging scripts, run from the repository root:
python -B -m unittest discover -s .github/scripts -p 'test_*.py'
For documentation-only changes, check wording, command examples and links. Keep Chinese and English documentation aligned; preserve commands, paths, variables and version information without changing their meaning in translation.
Use concise commit messages. The following prefixes are available as a reference:
| Prefix | Scope |
|---|---|
style(<name>): |
Theme presentation styles |
preview: |
Preview tools |
tools: |
CLI, build and snapshot tools |
docs: |
Documentation and translations |
fix: |
Bug fixes |
project: |
Repository configuration and project structure |
refactor: |
Code restructuring |
chore: |
Routine maintenance |
Version and Release Maintenance
Release tags must match the locked Gitea tag. Version labels, badges and compatibility records are maintained manually; changing official inputs does not trigger automatic version maintenance. Retain historical release assets and check documentation and compatibility records before tagging. After validation and generation of all previews, you can package manually from the repository root:
python .github/scripts/package_release.py --version v28.0.0 --output build/release-review
Replace the example version with the tag in the root lock file and use an output directory without release archives of the same name. The script checks source and artifact hashes, packages themes, previews, documentation, the official license and provenance, and excludes stale theme builds.
.github/workflows/validate.yml handles checks for ordinary pushes and pull requests and is also called by the Release workflow. After validation, Release packages the archives and uploads them through the release action. It uses the tag as the title and creates new releases with an empty body, without requiring a release notes file. Republishing an existing tag preserves its existing body and replaces same-name attachments. Check the release and attachment state before retrying a failed publication.
Workflows use the linux-amd64-docker-small runner label, with setup steps preparing Go, Python and Node.js for publication. Actions use actions/...@version references, resolved through the runner's action source configuration; consider the current github_mirror setting when maintaining them. Publication uses the built-in GITEA_TOKEN, and the repository must permit release writes.
Reporting Problems
Include the Gitea version, template release or source commit, theme, mail type, language and steps to reproduce. For build or preview issues, also include the tag in the root lock file, relevant commands and complete error output. For display issues, specify the mail client and attach screenshots with personal information removed.
For improvement suggestions, explain the use case, expected result and affected themes or tools. For official template or translation defects, preserve the original inputs and provide a minimal example that reproduces the issue.
License
This project uses the MIT License. Contribute code, styles and images that can be legally redistributed. When generating or distributing derived templates, retain Gitea copyright, the official license and snapshot provenance; release archives already include these files.