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

docs: modify contribution guides
Validate / Validate (push) Successful in 2m47s
Details

Browse Source
This commit is contained in:
KenanZhu committed 2026-10-12 10:18:29 +08:00
1 parent 8ccb5ac443
commit cb9382ade4
2 files changed
+567 -241
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

CONTRIBUTING.md
+285 -123
View File
@@ -1,12 +1,13 @@
# Contributing to Gitea Mail Templates
# Contributing
---
[简体中文](docs/CONTRIBUTING.zh-CN.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).
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](README.md#installation) and [compatibility matrix](COMPATIBILITY.md#compatibility-matrix).
## 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:
Use **Go 1.24 or later**. From the repository root, prepare the dependencies and locked official files, run the tests and generate the preview:
```bash
cd tools
@@ -16,35 +17,123 @@ 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.
Then open [preview/index.html](preview/index.html) in a browser, or run `go run . dev` for live preview. The validation and packaging workflows use Python 3.11.
The CLI uses urfave/cli and the x/net HTML parser. Python 3.11 or later is used by the documentation and packaging checks.
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](README.md#project-directory-structure) for the directory layout.
### Common Commands
> [!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.
Run these commands from `tools/`. Place flags before positional arguments.
## Development Tools
| Command | Result |
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-theme` is a theme name; quote paths containing spaces.
| Command | Purpose |
|---|---|
| `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 |
| `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 |
`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.
### upstream
## Adding a Theme
`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/`.
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.
| 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. |
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`.
To prepare inputs for the first time or check them independently, run:
```bash
go run . upstream prepare
go run . upstream verify
```
All three subcommands support `--root`, which defaults to `..` relative to the current working directory. For example:
```powershell
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`:
```bash
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:
```bash
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:
```powershell
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](README.md#install-a-theme) for installation.
> [!TIP]
> To change templates, edit theme sources, the shared framework or build adapter logic. Direct edits to generated `.tmpl` files are overwritten by subsequent builds and cause packaging provenance checks to fail.
### list
`list` displays theme names, modes and short descriptions, sorted by name:
```bash
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:
```bash
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:
```json
{
@@ -55,76 +144,128 @@ Theme names start with a lowercase letter and may contain lowercase letters, dig
}
```
| Mode | Generated presentation |
`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 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. |
| `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. |
### Shared Framework
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`.
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.
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.
`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:
After completing the theme, run the tests and generate a preview:
```bash
cd tools
go run . upstream sync --tag v28.0.0
go run . upstream verify
go test ./...
go run . preview my-theme
```
### delete
`delete` removes the source directories of one or more named themes:
```bash
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`:
```bash
go run . preview aurora
go run . preview aurora bloom
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 before updating compatibility records. `sync` changes the cache and lock only; documentation and release publication are separate steps. Use `prepare` for a missing cache.
| 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 |
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.
Default output includes `preview/rendered.js` and `preview/rendered/<locale>.js`. Open [preview/index.html](preview/index.html) in a browser; no server is required. See the [README](README.md#controls-and-keyboard-shortcuts) for controls and shortcuts.
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.
> [!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. Run `preview all` to restore every theme.
### Cache Recovery
To use a custom output path:
`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.
```bash
go run . preview --config ./data/templates_config.json --output ../build/preview-review/rendered.js all
```
For example, in PowerShell **from the repository root**, with an unused backup name:
> [!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 existing `preview/index.html` still 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:
```bash
go run . dev
```
Open [http://127.0.0.1:3456](http://127.0.0.1:3456). The default port is `3456`; use `--port` to change it:
```bash
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:
```bash
go run . help
go run . h
go run . help build
go run . preview --help
```
For `upstream` subcommand options, place `--help` after the subcommand:
```bash
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:
```powershell
Move-Item -LiteralPath .\build\upstream -Destination .\build\upstream.backup
@@ -133,70 +274,91 @@ 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.
> [!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.
### Known Upstream Formatting Issue
### Why does synchronizing a new version report changed adapter sources?
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.
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](COMPATIBILITY.md) after validation; a successful download does not establish compatibility.
## Verification and Release
### Why do some languages use English or produce formatting warnings?
### Checks for a Pull Request
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.
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 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.
For documentation or packaging changes, run from the repository root:
### 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](COMPATIBILITY.md#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](docs/images/README.md) 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/`:
```bash
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:
```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.
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.
### 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 the Go tests, documentation checks and preview generation.
2. Update documentation and compatibility records with the verification results. Release notes are optional and are not used as the Release body.
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 publishes only the archives, with the tag as the Release title and an empty body. Version labels, badges and compatibility records are maintained manually; review archive documentation before tagging. Confirm Actions support and write permissions on the configured Gitea host before relying on automated publication. See [version maintenance](COMPATIBILITY.md#version-maintenance).
### Gitea Workflow Configuration
The release workflow uses 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.
Publication uses [`gitea-release-action@v1.3.7`](https://gitea.com/actions/gitea-release-action/src/tag/v1.3.7/action.yml) directly, with the instance URL, repository, built-in `GITEA_TOKEN`, tag, title and the two archive paths. The Release body is empty when created; no notes file or Issue reminder is required. The repository must allow release writes. Action URLs explicitly use `https://gitea.com` rather than depending on `DEFAULT_ACTIONS_URL`.
Before publication, `actions/setup-node@v4` prepares Node.js 22. The current Gitea runner executes JavaScript actions with `node` from `PATH`; this provides the runtime interfaces used by the release action without `--experimental-fetch`. On repeated publication of an existing tag, the action preserves an existing body and replaces same-name attachments. It does not provide the previous script's draft-until-all-uploads-complete behavior. Review the release and attachments before retrying a failed publication.
## 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
Use concise commit messages. The following prefixes are available as a reference:
| Prefix | Scope |
|---|---|
| `style(<name>):` | Theme presentation |
| `preview:` | Browser preview |
| `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:` | Maintenance |
| `chore:` | Routine maintenance |
## Translations and License
### Version and Release Maintenance
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).
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:
```bash
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](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.