GiteaMailTemplates/CONTRIBUTING.md

Contributing to Gitea Mail Templates

Thanks for your interest in contributing! This project aims to provide a diverse, well-maintained collection of email templates for the Gitea ecosystem.

---

Ways to Contribute

Adding a New Style

1. Scaffold the new style: cd tools && go run . create <your-style-name> — this creates the directory structure with placeholder .tmpl files for all 11 email types
2. Edit each .tmpl file in themes/<your-style-name>/ with your unique visual design
3. Regenerate the preview: cd tools && go run . preview all — the build script auto-discovers all theme directories under themes/ and generates the theme selector dynamically
4. Submit a PR with screenshots of rendered emails

Style Guidelines

• Each style must include all 11 template types listed in the README
• Use only Gitea's built-in template functions — check the Gitea source for reference
• Translation keys must come from Gitea's official locale files (mail.* namespace)
• Never reference .DisplayName in templates where the data context lacks it (collaborator, transfer, release, workflow_run, assigned, default)
• Design for 600px max-width email clients
• Test against major email clients (Gmail, Outlook, Apple Mail) when possible

Bug Reports

If a template doesn't render correctly:

1. Check that all referenced Go template variables exist — compare against the Gitea source mail templates
2. Verify translation keys match Gitea's locale files
3. Confirm .DisplayName isn't used in templates that lack it
4. Regenerate the preview: cd tools && go run . preview all
5. Open an issue with: the style name, which email type, and the error or unexpected output

Documentation Improvements

Documentation updates, preview screenshots, installation guides, and translations are always welcome.

---

Development Setup

• Go 1.21+ for template rendering and the CLI tool
• Node.js 18+ (optional) for the live-reload dev server with Juice CSS inlining

Previewing Locally (Static)

1. Run cd tools && go run . preview all to generate rendered data
2. Open preview/index.html directly in a browser — no server needed
3. Use the theme switcher, template selector, and client mode toggles

Static Gmail/Outlook simulation is approximate. Use dev mode for accurate rendering.

Dev Server (Live Reload + CSS Inlining)

cd tools && go run . dev
# → http://localhost:3456

• Watches themes/**/*.tmpl — auto-rebuilds on save
• Runs Juice to inline <style> into style="" attributes
• Adds Outlook-compatible bgcolor/width HTML attributes
• Pushes live reload to browser via WebSocket
• Terminal output: themes/aurora/mail/repo/release.tmpl edited → [rebuild] done in 480ms

Integration Testing

Deploy the templates to a Gitea instance and use the admin test email feature: Site Administration > Configuration > Mailer > Send Test Email

---

Commit Conventions

• style(horizon|terminal|ember|bloom|heritage|neon|mono|terra|ink|aurora): — template changes
• preview: — preview tooling changes
• tools: — Go build script changes
• docs: — documentation and translations
• fix: — bug fixes
• project: — README, LICENSE, AGENTS.md, meta

---

Translations

• English
• Simplified Chinese
• Traditional Chinese
• Russian
• Japanese
• Korean

---

License

By contributing, you agree that your contributions will be licensed under the MIT License.