From 48541a5aeb66482928ebfe8ac072964f02619ad7 Mon Sep 17 00:00:00 2001 From: KenanZhu <3471685733@qq.com> Date: Fri, 12 Jun 2026 15:04:14 +0800 Subject: [PATCH] docs: update testing guidance, version requirement, and button color fix across all languages --- CONTRIBUTING.md | 26 ++++++++++++++++++-------- README.md | 10 ++++++---- docs/CONTRIBUTING.ja.md | 10 +++++++++- docs/CONTRIBUTING.ko.md | 10 +++++++++- docs/CONTRIBUTING.ru.md | 11 ++++++++++- docs/CONTRIBUTING.zh-CN.md | 11 +++++++++-- docs/CONTRIBUTING.zh-TW.md | 11 +++++++++-- docs/README.ja.md | 9 ++++++++- docs/README.ko.md | 9 ++++++++- docs/README.ru.md | 9 ++++++++- docs/README.zh-CN.md | 8 +++++++- docs/README.zh-TW.md | 8 +++++++- docs/images/README.md | 10 ++++++---- 13 files changed, 114 insertions(+), 28 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1883b66..5e2a3a2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -70,25 +70,35 @@ cd tools && go run . dev ### Integration Testing -Deploy the templates to a Gitea instance and use the admin test email feature: -**Site Administration > Configuration > Mailer > Send Test Email** +Deploy the templates to a Gitea instance and verify with real transactional emails. +The admin test email (**Site Administration > Configuration > Mailer > Send Test Email**) +does not use custom mail templates — it follows a built-in code path. + +The most reliable method is to trigger a real notification. For example, the password +reset flow: + +1. Log out and click **"Forgot password"** on the login page +2. Enter your account email and submit +3. Check the password reset email — it will render with your custom mail templates --- ## Commit Conventions +Any readable commit message in semantic format is welcome. Such as: + - `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 +- `preview(*):` — preview tooling changes +- `tools(*):` — Go build script changes +- `docs(*):` — documentation and translations +- `fix(*):` — bug fixes +- `project(*):` — README, LICENSE, AGENTS.md, meta --- ## Translations -- [English](CONTRIBUTING.md) +- English - [Simplified Chinese](docs/CONTRIBUTING.zh-CN.md) - [Traditional Chinese](docs/CONTRIBUTING.zh-TW.md) - [Russian](docs/CONTRIBUTING.ru.md) diff --git a/README.md b/README.md index c87eb3d..8481bfc 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ Every template is a drop-in replacement. All Go template variables, translation | ![Ink](docs/images/ink.png) | **Ink** | Publishing / News / Literature | Editorial print, navy & gold, newspaper layout, drop caps | | ![Aurora](docs/images/aurora.png) | **Aurora** | Premium SaaS / Mindfulness | Ethereal light gradients, deep purple & teal, atmospheric glow | -> Images are 600px screenshots from the [live preview](preview/index.html). See [docs/images/README.md](docs/images/README.md) for capture instructions. +> Images are screenshots from the [live preview](preview/index.html). See [docs/images/README.md](docs/images/README.md) for capture instructions. [**Live preview gallery**](preview/index.html) — open in a browser for an interactive style switcher with desktop/mobile viewports and email client simulation (Modern, Gmail, Outlook, Raw source). @@ -71,8 +71,10 @@ systemctl restart gitea ### Confirming It Works -Send a test email from the Gitea admin panel: -**Site Administration > Configuration > Mailer > Send Test Email** +The admin test email does not use custom mail templates. To verify your templates +are active, trigger a real email notification. The quickest way is the password +reset flow: log out, click **"Forgot password"** on the login page, and check the +reset email — it will render with your custom styles. --- @@ -168,7 +170,7 @@ gitea-mail-templates/ ## Compatibility -- **Gitea 1.21+** (all versions with Go 1.21 template support) +- **Gitea 1.25+** — matches the refactored mail template directory structure introduced in v1.25 - 100% variable-compatible with official Gitea templates - Uses only built-in Gitea template functions - Uses only official Gitea translation keys diff --git a/docs/CONTRIBUTING.ja.md b/docs/CONTRIBUTING.ja.md index 84eba69..fed65ce 100644 --- a/docs/CONTRIBUTING.ja.md +++ b/docs/CONTRIBUTING.ja.md @@ -55,7 +55,15 @@ cd tools && go run . dev ### 結合テスト -Gitea にデプロイ: **Site Administration > Configuration > Mailer > Send Test Email** +Gitea にデプロイ後、実際のトランザクションメールで検証してください。管理画面のテストメール +（**Site Administration > Configuration > Mailer > Send Test Email**）はカスタム +メールテンプレートを使用しません——組み込みのコードパスを通ります。 + +最も確実な方法は実際の通知をトリガーすることです。例えば、パスワードリセットフロー： + +1. ログアウトし、ログインページで **"Forgot password"** をクリック +2. アカウントのメールアドレスを入力して送信 +3. パスワードリセットメールを確認——カスタムメールテンプレートでレンダリングされます --- diff --git a/docs/CONTRIBUTING.ko.md b/docs/CONTRIBUTING.ko.md index 08fa22a..6a29611 100644 --- a/docs/CONTRIBUTING.ko.md +++ b/docs/CONTRIBUTING.ko.md @@ -55,7 +55,15 @@ cd tools && go run . dev ### 통합 테스트 -Gitea에 배포: **Site Administration > Configuration > Mailer > Send Test Email** +Gitea에 배포 후 실제 트랜잭션 이메일로 검증하세요. 관리자 테스트 이메일 +（**Site Administration > Configuration > Mailer > Send Test Email**）은 커스텀 +메일 템플릿을 사용하지 않습니다——내장 코드 경로를 따릅니다. + +가장 확실한 방법은 실제 알림을 트리거하는 것입니다. 예를 들어, 비밀번호 재설정 흐름: + +1. 로그아웃 후 로그인 페이지에서 **"Forgot password"** 클릭 +2. 계정 이메일을 입력하고 제출 +3. 비밀번호 재설정 이메일 확인——커스텀 메일 템플릿으로 렌더링됩니다 --- diff --git a/docs/CONTRIBUTING.ru.md b/docs/CONTRIBUTING.ru.md index e194aa1..0b6cf74 100644 --- a/docs/CONTRIBUTING.ru.md +++ b/docs/CONTRIBUTING.ru.md @@ -55,7 +55,16 @@ cd tools && go run . dev ### Интеграционное тестирование -Разверните на Gitea: **Site Administration > Configuration > Mailer > Send Test Email** +Разверните шаблоны на Gitea и проверяйте с реальными транзакционными письмами. +Тестовое письмо администратора (**Site Administration > Configuration > Mailer > +Send Test Email**) не использует пользовательские шаблоны — оно идет по +встроенному пути. + +Самый надежный способ — вызвать реальное уведомление. Например, сброс пароля: + +1. Выйдите из системы и нажмите **"Forgot password"** на странице входа +2. Введите email вашей учетной записи и отправьте +3. Проверьте письмо для сброса пароля — оно будет отрендерено с вашими шаблонами --- diff --git a/docs/CONTRIBUTING.zh-CN.md b/docs/CONTRIBUTING.zh-CN.md index b71a622..8dc5958 100644 --- a/docs/CONTRIBUTING.zh-CN.md +++ b/docs/CONTRIBUTING.zh-CN.md @@ -59,8 +59,15 @@ cd tools && go run . dev ### 集成测试 -将模板部署到 Gitea 实例，使用管理后台的测试邮件功能： -**Site Administration > Configuration > Mailer > Send Test Email** +将模板部署到 Gitea 实例后，请通过真实的邮件通知进行验证。管理后台的测试邮件 +（**Site Administration > Configuration > Mailer > Send Test Email**）不会使用 +自定义邮件模板——它走的是内置代码路径。 + +最可靠的验证方式是触发一次真实的邮件通知，推荐使用密码重置流程： + +1. 退出登录，点击登录页的**"忘记密码"** +2. 输入账户邮箱并提交 +3. 查看密码重置邮件——它将使用你的自定义邮件模板渲染 --- diff --git a/docs/CONTRIBUTING.zh-TW.md b/docs/CONTRIBUTING.zh-TW.md index 87f453a..770aa02 100644 --- a/docs/CONTRIBUTING.zh-TW.md +++ b/docs/CONTRIBUTING.zh-TW.md @@ -59,8 +59,15 @@ cd tools && go run . dev ### 整合測試 -將模板部署至 Gitea 實例，使用管理後台的測試郵件功能： -**Site Administration > Configuration > Mailer > Send Test Email** +將模板部署至 Gitea 實例後，請透過真實的郵件通知進行驗證。管理後台的測試郵件 +（**Site Administration > Configuration > Mailer > Send Test Email**）不會使用 +自訂郵件模板——它走的是內置程式碼路徑。 + +最可靠的驗證方式是觸發一次真實的郵件通知，推薦使用密碼重設流程： + +1. 登出帳號，點擊登入頁的**"忘記密碼"** +2. 輸入帳戶郵箱並提交 +3. 查看密碼重設郵件——它將使用你的自訂郵件模板渲染 --- diff --git a/docs/README.ja.md b/docs/README.ja.md index 58f0acf..66955ec 100644 --- a/docs/README.ja.md +++ b/docs/README.ja.md @@ -34,6 +34,13 @@ cp -r themes/horizon/mail/* /var/lib/gitea/custom/templates/mail/ systemctl restart gitea ``` +### 動作確認 + +管理画面のテストメールはカスタムテンプレートを使用しません。テンプレートが +有効であることを確認するには、実際のメール通知をトリガーしてください。最も +簡単な方法はパスワードリセットです：ログアウトし、ログインページで +**"Forgot password"** をクリックし、リセットメールを確認してください。 + ## プレビュー **静的モード:** @@ -53,7 +60,7 @@ cd tools && go run . dev # Node.jsが必要です ## 互換性 -- **Gitea 1.21+**, 100%互換, 組み込み関数のみ +- **Gitea 1.25+**, 100%互換, 組み込み関数のみ ## ライセンス diff --git a/docs/README.ko.md b/docs/README.ko.md index 2f526ee..db3d5b7 100644 --- a/docs/README.ko.md +++ b/docs/README.ko.md @@ -34,6 +34,13 @@ cp -r themes/horizon/mail/* /var/lib/gitea/custom/templates/mail/ systemctl restart gitea ``` +### 작동 확인 + +관리자 테스트 이메일은 커스텀 템플릿을 사용하지 않습니다. 템플릿이 활성화 +되었는지 확인하려면 실제 이메일 알림을 트리거하세요. 가장 빠른 방법은 비밀번호 +재설정입니다: 로그아웃 후 로그인 페이지에서 **"Forgot password"** 를 클릭하고 +재설정 이메일을 확인하세요. + ## 프리뷰 **정적 모드:** @@ -53,7 +60,7 @@ cd tools && go run . dev # Node.js 필요 ## 호환성 -- **Gitea 1.21+**, 100% 호환, 내장 함수만 사용 +- **Gitea 1.25+**, 100% 호환, 내장 함수만 사용 ## 라이선스 diff --git a/docs/README.ru.md b/docs/README.ru.md index 8489249..cdc2550 100644 --- a/docs/README.ru.md +++ b/docs/README.ru.md @@ -34,6 +34,13 @@ cp -r themes/horizon/mail/* /var/lib/gitea/custom/templates/mail/ systemctl restart gitea ``` +### Проверка работы + +Тестовое письмо администратора не использует пользовательские шаблоны. Чтобы +убедиться, что шаблоны активны, вызовите реальное уведомление. Самый быстрый +способ — сброс пароля: выйдите из системы, нажмите **"Forgot password"** на +странице входа и проверьте письмо для сброса. + ## Предпросмотр **Статический режим:** @@ -53,7 +60,7 @@ cd tools && go run . dev # требуется Node.js ## Совместимость -- **Gitea 1.21+**, 100% совместимость, только встроенные функции +- **Gitea 1.25+**, 100% совместимость, только встроенные функции ## Лицензия diff --git a/docs/README.zh-CN.md b/docs/README.zh-CN.md index 8883523..b5808b0 100644 --- a/docs/README.zh-CN.md +++ b/docs/README.zh-CN.md @@ -46,6 +46,12 @@ systemctl restart gitea 切换风格只需覆盖文件，无需更改配置。 +### 确认生效 + +管理后台的测试邮件不会使用自定义模板。要验证模板是否生效，请触发一次真实的 +邮件通知。最快的方式是密码重置：退出登录，点击登录页的**"忘记密码"**，查看 +重置邮件即可——它将使用你的自定义样式渲染。 + --- ## 预览 @@ -81,7 +87,7 @@ cd tools && go run . dev # 需要 Node.js ## 兼容性 -- **Gitea 1.21+**，100% 变量兼容，仅使用内置函数和官方翻译键 +- **Gitea 1.25+**，100% 变量兼容，仅使用内置函数和官方翻译键 ## 许可证 diff --git a/docs/README.zh-TW.md b/docs/README.zh-TW.md index 125fe9a..14fdd15 100644 --- a/docs/README.zh-TW.md +++ b/docs/README.zh-TW.md @@ -46,6 +46,12 @@ systemctl restart gitea 切換風格只需覆蓋檔案，無需更改設定。 +### 確認生效 + +管理後台的測試郵件不會使用自訂模板。要驗證模板是否生效，請觸發一次真實的 +郵件通知。最快的方式是密碼重設：登出帳號，點擊登入頁的**"忘記密碼"**，查看 +重設郵件即可——它將使用你的自訂樣式渲染。 + --- ## 預覽 @@ -69,7 +75,7 @@ cd tools && go run . dev # 需要 Node.js ## 相容性 -- **Gitea 1.21+**，100% 變數相容，僅使用內建函式和官方翻譯鍵 +- **Gitea 1.25+**，100% 變數相容，僅使用內建函式和官方翻譯鍵 ## 授權 diff --git a/docs/images/README.md b/docs/images/README.md index 2039eca..0786413 100644 --- a/docs/images/README.md +++ b/docs/images/README.md @@ -1,6 +1,6 @@ # Style Preview Images -Place 600px-wide PNG screenshots here, captured from the [live preview](../preview/index.html). +Place theme style screenshots of **Desktop** in PNG format here, captured from the [live preview](../preview/index.html). ## Naming Convention @@ -11,14 +11,16 @@ neon.png mono.png terra.png ink.png aurora.png ## Image Size Requirements +To ensure screenshots can be displayed in the README, please follow these size requirements: + - **Maximum:** 50 KiB per image -- **Recommended:** 10–20 KiB +- **Recommended:** 30–40 KiB - **Format:** PNG, optimised — run through `pngquant` or `optipng` before committing ## How to Capture -1. Start the dev server: `cd tools && go run . dev` (opens http://localhost:3456) -2. For each style, select the "Activate Account" template and "Modern" client mode +1. Start the dev server: `cd tools && go run . dev` (opens http://localhost:3456 in your browser) +2. For each style, select the **"Activate Account"** template and **"Modern"** client mode in **"Desktop"** 3. Take a screenshot of the rendered email (600px width recommended) 4. Save as `.png` in this directory