diff --git a/AGENTS.md b/AGENTS.md index 6ba7f3d0..4485b6d6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,6 +29,7 @@ Binding for every AI agent (Claude, Codex, Cursor, review bots, …). CLAUDE.md - Local-first: no new required network calls; any HF download gated on installed-ness or explicit user action; all synthetic audio through the `mark_synthetic` chokepoint. - Every user-facing string via i18n, present in ALL 21 `frontend/src/i18n/locales/*.json` with real translations. - Docs-sync in the same PR. CHANGELOG Unreleased: quiet one-liners ending `(#N)` + `— thanks @user!` for community work, under a short `**Highlights**` list. +- Tagged release announcements lead with the biggest user-visible change; redesigns need real UI screenshots and migrations need installer links and steps. Verify all contributor credits from the tag comparison and included PRs; list authors and bug reporters separately (see `docs/RELEASING.md`). - Versioning: `frontend/package.json` is the single source of truth; never bump without the owner asking. - `frontend/package.json` dep changes require regenerating root `bun.lock` (Docker runs `--frozen-lockfile`). - Issues: absorb or decline — never defer to a future version. Check the open-PR queue before implementing community-reported fixes. diff --git a/CLAUDE.md b/CLAUDE.md index d6ed9cda..f8b1dfdd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -46,6 +46,8 @@ For anything new: prefer what's already pinned in `pyproject.toml` / `frontend/p **Release notes / changelog (hard rule, owner-set 2026-06-16):** every tagged release gets a **high-quality, user-facing `## [X.Y.Z] — DATE` section in `CHANGELOG.md`** before (or in the same hour as) the tag — never the "Auto-generated release for vX.Y.Z…" fallback. `release.yml` extracts that section verbatim as the GitHub Release body (the `Extract CHANGELOG section for tag` step), so a missing/empty section ships a bare release. Quality bar (owner-restyled 2026-07-17, replaces the old bold-lead paragraphs): **quiet and scannable** — a short `**Highlights**` bullet list first (plain words, one line each), then `### Changed` / `### Added` / `### Docs` / `### Fixed` / `### License` / `### CI` subsections where each entry is a **single one-liner** with the `(#NNN)` issue/PR ref and contributor credit (`— thanks @user!`) where applicable. Written for users, grouped by theme, no multi-line paragraphs, **not** raw commit dumps. This applies to **preview builds too**: preview release notes summarize what's new on `main` since the last stable, in the same style. Workflow: as features merge, keep `## [Unreleased]` current; at release time rename it to the version + date. If a release was already cut with the fallback body, the next action is to backfill `CHANGELOG.md` **and** `gh release edit ` the live body — not backlog. +**Release presentation and credits (owner-set 2026-09-17):** Tagged release announcements lead with the biggest user-visible change; redesigns need real UI screenshots and migrations need installer links and steps. Verify all contributor credits from the tag comparison and included PRs; list authors and bug reporters separately (see `docs/RELEASING.md`). Keep Highlights to 3–5 bullets; the release introduction can include prose, images, and a download table before the concise change entries. + **Localization (hard rule):** No hardcoded non-English (CJK) **user-facing text** anywhere in the codebase except the translation layer (`frontend/src/i18n/`). All UI strings go through i18n (`t('...')` keys in `locales/*.json`); native language names live in `i18n/index.ts` (`LANGUAGES`). Functional CJK is allowed and tracked via the allowlist in `tests/test_no_hardcoded_cjk.py` — text-processing regexes, model/engine vocabulary & identifiers (e.g. CosyVoice speaker IDs), localized error matching, demo/eval data, and test fixtures. CI fails on any hardcoded CJK outside the allowlist; to add legitimate functional CJK, extend `_ALLOWED_FILES` there with a justification. **Release deployment channels (hard rule, owner-set 2026-07-16):** a version bump is not "released" until **every** deployment channel ships it — the full checklist (sources, producing workflows, per-channel verification) lives in `docs/RELEASING.md` §5b. The channels: GitHub Release with 4-platform installers + signed `latest.json` (Stable updater channel, body from CHANGELOG); the Preview updater channel; GHCR **and** Docker Hub images in **both** flavors (CUDA `:X.Y.Z`/`:X.Y`/`:stable`, ROCm `-rocm` suffixes); the Docker Hub overview page synced from `deploy/dockerhub-overview.md` (its sync step is `continue-on-error` and 403s silently if `DOCKERHUB_TOKEN` lacks description-edit scope — verify the **step log**, never just job-green). Verify all channels after tagging; a missing channel is a release bug to fix immediately, not backlog. **Preview/RC always sources from `main`:** there are no RC tags — the rolling preview channel (preview `latest.json`, Docker `:latest`/`:main`/`:rocm`) *is* the RC, it always builds from `main` (release.yml's preview-gate refuses other branches), and previewing a fix means merging it to `main` first. Never cut a side-branch build. diff --git a/docs/RELEASING.md b/docs/RELEASING.md index 5b5b3b25..6ef8d14c 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -58,6 +58,20 @@ does not update clients already on `v0.2.1`. ## 5. Cutting a release +Release notes lead with the biggest user-visible change, not README edits or +packaging internals. For a desktop redesign or migration, include a real UI +screenshot pinned to the release tag, explain what changed, and give direct +installer links and migration steps. Keep Highlights to 3–5 bullets, followed +by concise themed entries. Preserve any installer-trust disclosures. + +Verify credits against the previous-tag-to-new-tag commit comparison and the +included PRs, including contributor branches merged through maintainer branches. +Add a Contributors section naming every human author and their contribution; +thank verified bug reporters separately and identify dependency bots separately. +Do not infer contributors from the existing changelog's `thanks` entries alone. +Electron publishes the authored version section verbatim, with any required +installer-trust disclosure appended by the workflow. + 1. **CHANGELOG first (hard rule):** make sure `CHANGELOG.md` has a complete, user-facing `## [X.Y.Z] — DATE` section (rename `## [Unreleased]`). `release.yml` extracts that section verbatim as the GitHub Release body —