preview: improve sidebar layout and screenshot export
Validate / Validate (push) Successful in 3m29s
Validate / Validate (push) Successful in 3m29s
This commit is contained in:
KenanZhu committed
1 parent
e51e2e9996
commit
6733e81356
8 files changed
+259
-118
No files matched your search
+10
-27
@@ -1,6 +1,6 @@
|
||||
# Contributing to Gitea Mail Templates
|
||||
|
||||
[简体中文](docs/CONTRIBUTING.zh-CN.md) · [Project overview](README.md) · [Compatibility](COMPATIBILITY.md)
|
||||
[简体中文](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).
|
||||
|
||||
@@ -18,7 +18,7 @@ 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.
|
||||
The CLI uses urfave/cli and the x/net HTML parser. Python 3.11 or later is used by the documentation and packaging checks.
|
||||
|
||||
### Common Commands
|
||||
|
||||
@@ -114,7 +114,7 @@ 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.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
@@ -145,7 +145,7 @@ Gitea v28.0.0 contains a Polish `mail.team_invite.text_1` placeholder defect. Pr
|
||||
|
||||
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:
|
||||
For documentation or packaging changes, run from the repository root:
|
||||
|
||||
```bash
|
||||
python -B -m unittest discover -s .github/scripts -p 'test_*.py'
|
||||
@@ -153,29 +153,12 @@ 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.
|
||||
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.
|
||||
|
||||
@@ -187,15 +170,15 @@ python .github/scripts/package_release.py --version vX.Y.Z --output <new-output-
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
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`.
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
|
||||
Reference in new issue
Block a user