From 7be35101bdad0758c5c1a7f5564896fbe57da466 Mon Sep 17 00:00:00 2001 From: fylorn <249551762+fylorn@users.noreply.github.com> Date: Fri, 20 Nov 2026 23:02:58 +0800 Subject: [PATCH] feat(updater): localize in-app release notes Keep the Chinese tag summary in the standard updater field and pass the English release summary in an additional manifest field. Select the summary using the active interface language so language changes also update a window that is already open. Require both summaries for future releases. Keep older manifests usable and omit the notes when the selected language is unavailable. --- .github/workflows/release.yml | 17 ++++++--- CONTRIBUTING.md | 42 +++++++++++----------- scripts/manifest.py | 27 ++++++++++++--- scripts/release_notes.py | 8 ++--- scripts/release_notes_test.py | 21 +++++++++++ src-tauri/src/updater.rs | 65 ++++++++++++++++++++++++++++++----- src/UpdateWindow.tsx | 7 ++-- src/updateFlow.test.ts | 17 ++++++++- src/updateFlow.ts | 14 ++++++-- 9 files changed, 168 insertions(+), 50 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 8f608db6..5a3606eb 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -753,6 +753,14 @@ jobs: fi echo "VERSION=$GOT" >> "$GITHUB_ENV" + - name: A published release has an English summary + if: github.ref_type == 'tag' + run: | + if [ ! -f "release-notes/$VERSION.md" ]; then + echo "缺少英文发布说明:release-notes/$VERSION.md" >&2 + exit 1 + fi + # 清单向 GitHub 要:和它在发布页上「自动生成」的是同一份。演练时这个 tag # 可能还不存在,那就算到这次的 commit 为止(tag 存在时 target_commitish 不起作用) - name: Write it @@ -790,9 +798,8 @@ jobs: - run: echo "VERSION=${GITHUB_REF_NAME#v}" >> "$GITHUB_ENV" - # tag 上那段话写进 latest.json,是给已经装上的应用的发布说明(2026.9.13 - # 之前的版本在更新窗口里显示它)—— 自动生成的提交清单在那个位置对用户 - # 没有意义。发布页上的正文是另一份,见 `release-body`。 + # tag 注解给应用的更新窗口提供中文说明。manifest.py 也会从 + # release-notes/<版本>.md 读出英文摘要,供英文界面使用。 # # **不从工作区的 git 里读。**`actions/checkout` 取 tag 时建的是一个 # 直接指向 commit 的轻量引用,注解对象根本不在这个克隆里; @@ -806,7 +813,7 @@ jobs: set -euo pipefail : > notes.txt REF="repos/$GITHUB_REPOSITORY/git/ref/tags/$GITHUB_REF_NAME" - # 轻量 tag 指向的是 commit,没有正文可取 —— 那就不写发布说明。 + # 轻量 tag 取不到注解,manifest.py 会报缺少中文发布说明。 if [ "$(gh api "$REF" --jq .object.type)" = tag ]; then SHA=$(gh api "$REF" --jq .object.sha) gh api "repos/$GITHUB_REPOSITORY/git/tags/$SHA" --jq .message \ @@ -825,7 +832,7 @@ jobs: - name: One manifest for every platform run: | set -euo pipefail - python3 scripts/manifest.py "$VERSION" notes.txt \ + python3 -B scripts/manifest.py "$VERSION" notes.txt \ "darwin-aarch64=dist/ThinkWatch-Lite-$VERSION-darwin-arm64.dmg" \ "windows-x86_64=dist/ThinkWatch-Lite-$VERSION-windows-x64-setup.exe" \ "windows-aarch64=dist/ThinkWatch-Lite-$VERSION-windows-arm64-setup.exe" \ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4cf0559c..a0eaa9d4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -201,28 +201,26 @@ change to `release.yml`, push the branch as `rehearse/`: every job runs and the installers are kept as the run's artifacts, but nothing is published. -A release has two texts: - -- **The tag message.** Its first line is `ThinkWatch Lite `; the - rest becomes the `notes` of `latest.json`, the manifest for in-app - updates. It is not shown on the release page. -- **The release page**, titled `ThinkWatch Lite ` and written in - English by `scripts/release_notes.py`, in this order: - 1. `release-notes/.md`, when that file exists: a summary of the - release in paragraphs or lists, without a top-level heading. Add it in - the pull request that bumps the version, because the tag fixes what - the tree contains. - 2. A table of the file for each platform, and the Homebrew and Linux - install commands. - 3. How to verify a download against its `.sha256`. - 4. GitHub's list of the pull requests merged since the previous release. - - The text is written when the release is created. A release that already - exists keeps its text, so a correction after publishing is made on the - release page itself. CI runs `python3 scripts/release_notes_test.py`, - which checks the script against `release.yml` and renders every file in - `release-notes/`; a rehearsal shows the complete text in the summary of - its run. +Each published release needs two Markdown summaries for the in-app update window. + +- Write the **Chinese summary** in the annotated tag message after the + `ThinkWatch Lite ` title and a blank line. It becomes `notes` + in `latest.json`. +- Add the **English summary** at `release-notes/.md` in the pull + request that bumps the version. Use paragraphs or lists and start any + headings at level two. It becomes `notes_en` in `latest.json` and the + first section of the GitHub release page. + +The release page is titled `ThinkWatch Lite ` and generated by +`scripts/release_notes.py`. After the English summary, it lists the +downloads and install commands, explains how to verify the downloads, +and includes GitHub's list of pull requests merged since the previous release. + +The text is written when the release is created. To correct it after +publication, edit the release page directly. CI runs +`python3 scripts/release_notes_test.py` to check the release scripts and +every file in `release-notes/`. A rehearsal shows the release page text +in the run summary and can run before the English summary is written. ## Product screenshots diff --git a/scripts/manifest.py b/scripts/manifest.py index a69abc6d..8fb4436f 100755 --- a/scripts/manifest.py +++ b/scripts/manifest.py @@ -8,7 +8,9 @@ Linux 上只发 AppImage,它原地换掉自己(见 `src-tauri/src/update.rs`); `scripts/install.sh` 也从这一份里找本架构的 AppImage。 -用法:manifest.py <版本> <发布说明文件> <平台>=<文件> [<平台>=<文件> ...] +用法:manifest.py <版本> <中文发布说明文件> <平台>=<文件> [<平台>=<文件> ...] + +中文说明沿用 Tauri 的 notes 字段;英文说明取 release-notes/<版本>.md,写在 notes_en。 清单里的 URL 必须和最终挂在 release 上的文件名一字不差,所以文件名不在 这里拼:文件的路径由调用方传进来,URL 用的就是它的名字。两处各拼一遍的 @@ -26,6 +28,8 @@ import pathlib import sys +from release_notes import NOTES_DIR, NotesError, summary + REPO = "ThinkWatchProject/ThinkWatch-Lite" # 平台键由更新器自己拼:目标系统 + 架构(macOS 上叫 darwin)。**只收这几个** # —— 拼错一个字母,那个平台的用户就永远问不到新版本,而清单看起来完好。 @@ -88,10 +92,25 @@ def entry(path: pathlib.Path, version: str, want: bytes) -> dict: } +def update_notes(version: str, chinese_file: pathlib.Path, notes_dir: pathlib.Path = NOTES_DIR) -> dict[str, str]: + """老版本仍从 notes 读中文,新版本按语言读对应的一份。""" + chinese = chinese_file.read_text(encoding="utf-8").strip() + if not chinese: + raise NotesError(f"v{version} 的 tag 注解缺少中文发布说明:在标题和空行之后填写正文") + english = summary(version, notes_dir) + if english is None: + raise NotesError(f"缺少英文发布说明:release-notes/{version}.md") + return {"notes": chinese, "notes_en": english} + + def main() -> None: if len(sys.argv) < 4: - sys.exit("用法:manifest.py <版本> <发布说明文件> <平台>=<文件> [...]") + sys.exit("用法:manifest.py <版本> <中文发布说明文件> <平台>=<文件> [...]") version, notes_file, pairs = sys.argv[1], sys.argv[2], sys.argv[3:] + try: + notes = update_notes(version, pathlib.Path(notes_file)) + except NotesError as e: + sys.exit(str(e)) root = pathlib.Path(__file__).resolve().parent.parent conf = json.loads((root / "src-tauri/tauri.conf.json").read_text(encoding="utf-8")) @@ -121,10 +140,8 @@ def main() -> None: .isoformat() .replace("+00:00", "Z"), "platforms": platforms, + **notes, } - notes = pathlib.Path(notes_file).read_text(encoding="utf-8").strip() - if notes: - manifest["notes"] = notes out = pathlib.Path(pairs[0].partition("=")[2]).parent / "latest.json" out.write_text(json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") diff --git a/scripts/release_notes.py b/scripts/release_notes.py index 18dd02a8..ba5cf64d 100755 --- a/scripts/release_notes.py +++ b/scripts/release_notes.py @@ -5,7 +5,7 @@ 正文是英文的,依次是: -1. `release-notes/<版本>.md`:这一版的说明。**可以没有**,没有就从下载表开始。 +1. `release-notes/<版本>.md`:这一版的英文说明。正式发版时必须提供,演练时可省略。 2. 下载表:每个文件一行(Windows 每个架构两行:安装程序、绿色版 zip),文件名和 release.yml 挂上去的一字不差;再给 Homebrew 和 Linux 安装脚本的命令、绿色版的 用法。 @@ -14,8 +14,8 @@ 调用方用 `gh api repos/<仓库>/releases/generate-notes` 取来。拆成参数传进来, 这个脚本就不碰网络,测试可以直接喂它。 -**tag 的注解不在这里。**那段中文写进 latest.json(见 manifest.py),是给已经装上 -的应用的;发布页面向从网页来下载的人。 +应用的英文更新说明也取这份摘要。tag 注解里的中文说明和英文摘要一起写进 +latest.json(见 manifest.py)。 说明文件写坏了(有中文、有一级标题、是空的)就不写正文 —— 发版流水线在这一步 停下,比发出去再改好。CI 在每个 PR 上把 `release-notes/` 下的每一份都过一遍 @@ -68,7 +68,7 @@ def summary(version: str, notes_dir: pathlib.Path = NOTES_DIR) -> str | None: text = path.read_text(encoding="utf-8").strip() name = f"release-notes/{path.name}" if not text: - raise NotesError(f"{name} 是空的:没有要说的就删掉这个文件") + raise NotesError(f"{name} 是空的:请填写英文发布说明") for n, line in enumerate(text.splitlines(), 1): if CJK.search(line): raise NotesError( diff --git a/scripts/release_notes_test.py b/scripts/release_notes_test.py index 4ca6d034..eff480a7 100755 --- a/scripts/release_notes_test.py +++ b/scripts/release_notes_test.py @@ -164,6 +164,27 @@ def test_the_portable_build_has_its_own_keys(self): self.assertEqual(manifest.PLATFORMS["windows-x86_64-portable"], "-windows-x64-portable.zip") self.assertEqual(manifest.PLATFORMS["windows-aarch64-portable"], "-windows-arm64-portable.zip") + def test_update_notes_keep_the_legacy_field_and_add_english(self): + d = notes_dir(self, { + "tag.txt": " \n- 修复路由\n", + "2026.9.16.md": "\n- Fixed routing\n", + }) + self.assertEqual( + manifest.update_notes("2026.9.16", d / "tag.txt", d), + {"notes": "- 修复路由", "notes_en": "- Fixed routing"}, + ) + + def test_publishing_requires_both_summaries_for_the_same_release(self): + d = notes_dir(self, { + "tag.txt": "修复路由", + "empty-tag.txt": "\n ", + "2026.9.15.md": "Previous release", + }) + with self.assertRaisesRegex(rn.NotesError, r"release-notes/2026\.9\.16\.md"): + manifest.update_notes("2026.9.16", d / "tag.txt", d) + with self.assertRaisesRegex(rn.NotesError, "缺少中文发布说明"): + manifest.update_notes("2026.9.15", d / "empty-tag.txt", d) + class Summary(unittest.TestCase): def test_absent_is_none(self): diff --git a/src-tauri/src/updater.rs b/src-tauri/src/updater.rs index c148291a..27a87e9c 100644 --- a/src-tauri/src/updater.rs +++ b/src-tauri/src/updater.rs @@ -54,7 +54,25 @@ pub async fn set_update_check(app: tauri::AppHandle, on: bool) -> Out, + #[serde(skip_serializing)] + notes: ReleaseNotes, +} + +#[derive(Clone, Default, serde::Serialize)] +struct ReleaseNotes { + zh: Option, + en: Option, +} + +impl ReleaseNotes { + fn from_manifest(zh: Option, raw: &serde_json::Value) -> Self { + // Tauri 已读了标准的 notes(中文),英文在同一份清单的附加字段里。 + let en = raw + .get("notes_en") + .and_then(|v| v.as_str()) + .map(str::to_owned); + Self { zh, en } + } } /// 更新在内存里的那点状态。 @@ -70,7 +88,7 @@ pub struct Updates { #[derive(serde::Serialize)] pub struct OfferView { version: String, - notes: Option, + notes: ReleaseNotes, current: String, install: update::Install, /// Homebrew 那一档要执行的命令。**由这里给出,界面上不再写一遍** —— @@ -85,7 +103,7 @@ async fn look(app: &tauri::AppHandle) -> Result, String> { let found = updater(app)?.check().await.map_err(|e| e.to_string())?; Ok(found.map(|up| Found { version: up.version, - notes: up.body, + notes: ReleaseNotes::from_manifest(up.body, &up.raw_json), })) } @@ -172,7 +190,8 @@ fn brew_offer(version: &str, release: Option) -> Found { version: version.to_string(), notes: release .filter(|r| r.version == version) - .and_then(|r| r.notes), + .map(|r| r.notes) + .unwrap_or_default(), } } @@ -979,22 +998,52 @@ mod tests { use crate::i18n::{Lang, with_lang}; use notices::Mode; + #[test] + fn release_notes_read_both_languages_from_the_same_manifest() { + let manifest = serde_json::json!({ + "version": "2026.11.20", + "notes": "修复路由", + "notes_en": "Fixed routing", + "platforms": {}, + }); + let release: tauri_plugin_updater::RemoteRelease = + serde_json::from_value(manifest.clone()).unwrap(); + let notes = ReleaseNotes::from_manifest(release.notes, &manifest); + assert_eq!(notes.zh.as_deref(), Some("修复路由")); + assert_eq!(notes.en.as_deref(), Some("Fixed routing")); + } + + #[test] + fn older_or_malformed_manifests_can_still_offer_an_update() { + for manifest in [serde_json::json!({}), serde_json::json!({ "notes_en": 42 })] { + let notes = ReleaseNotes::from_manifest(Some("修复路由".into()), &manifest); + assert_eq!(notes.zh.as_deref(), Some("修复路由")); + assert_eq!(notes.en, None); + } + } + #[test] fn brew_uses_notes_only_for_the_version_in_the_cask() { let release = Found { version: "2026.11.20".into(), - notes: Some("Release notes".into()), + notes: ReleaseNotes { + zh: Some("修复路由".into()), + en: Some("Fixed routing".into()), + }, }; let matching = brew_offer("2026.11.20", Some(release.clone())); - assert_eq!(matching.notes.as_deref(), Some("Release notes")); + assert_eq!(matching.notes.zh.as_deref(), Some("修复路由")); + assert_eq!(matching.notes.en.as_deref(), Some("Fixed routing")); let behind = brew_offer("2026.11.19", Some(release)); assert_eq!(behind.version, "2026.11.19"); - assert_eq!(behind.notes, None); + assert_eq!(behind.notes.zh, None); + assert_eq!(behind.notes.en, None); let unavailable = brew_offer("2026.11.20", None); assert_eq!(unavailable.version, "2026.11.20"); - assert_eq!(unavailable.notes, None); + assert_eq!(unavailable.notes.zh, None); + assert_eq!(unavailable.notes.en, None); } /// 「已更新到 x」和别的告知同一个开关:**只在「系统通知」那一档弹** diff --git a/src/UpdateWindow.tsx b/src/UpdateWindow.tsx index 35a7be29..0146261b 100644 --- a/src/UpdateWindow.tsx +++ b/src/UpdateWindow.tsx @@ -11,9 +11,9 @@ import { Spinner } from "@/ui/spinner"; import { StatusDot } from "@/ui/status-dot"; import { IconCopied, IconCopy } from "@/ui/icons"; import { Markdown } from "@/traffic/Markdown"; -import { useText } from "@/i18n"; +import { useLang, useText } from "@/i18n"; import { commonText } from "@/i18n/common.i18n"; -import { canInstall, describeStep, type Offer, type Step } from "./updateFlow"; +import { canInstall, describeStep, releaseNotesFor, type Offer, type Step } from "./updateFlow"; import { updateText } from "./Update.i18n"; import { errorText } from "@/i18n/core.i18n"; @@ -41,6 +41,7 @@ const COPIED_MS = 2_000; * 内容一边展开、窗口一边一格格地改尺寸,比直接换过去难看。 */ export default function UpdateWindow() { + const lang = useLang(); const t = useText(updateText); const common = useText(commonText); const [offer, setOffer] = useState(null); @@ -119,7 +120,7 @@ export default function UpdateWindow() { if (!offer) return null; const busy = step !== null && failed === null; - const notes = busy ? null : offer.notes?.trim(); + const notes = busy ? null : releaseNotesFor(offer.notes, lang); const install = async () => { setFailed(null); diff --git a/src/updateFlow.test.ts b/src/updateFlow.test.ts index 761e46aa..b319cc8c 100644 --- a/src/updateFlow.test.ts +++ b/src/updateFlow.test.ts @@ -1,6 +1,21 @@ import { describe, expect, it } from "vitest"; import { setLang } from "./i18n"; -import { canInstall, describeStep } from "./updateFlow"; +import { canInstall, describeStep, releaseNotesFor } from "./updateFlow"; + +describe("更新说明按界面语言选取", () => { + it("分别展示中文和英文,并保留 Markdown 的换行", () => { + const notes = { zh: " - 修复路由\n- 改进更新\n", en: " - Fixed routing\n- Improved updates\n" }; + expect(releaseNotesFor(notes, "zh")).toBe("- 修复路由\n- 改进更新"); + expect(releaseNotesFor(notes, "en")).toBe("- Fixed routing\n- Improved updates"); + }); + + it("旧清单只有中文时英文界面隐藏说明", () => { + const notes = { zh: "修复路由", en: null }; + expect(releaseNotesFor(notes, "zh")).toBe("修复路由"); + expect(releaseNotesFor(notes, "en")).toBeUndefined(); + expect(releaseNotesFor({ zh: " ", en: "Fixed routing" }, "zh")).toBeUndefined(); + }); +}); describe("谁能在窗口里直接装", () => { /** diff --git a/src/updateFlow.ts b/src/updateFlow.ts index 4918964a..d9988e9d 100644 --- a/src/updateFlow.ts +++ b/src/updateFlow.ts @@ -4,7 +4,7 @@ * 更新窗口和设置页都用它们。**判断在 Rust 里**(这一份怎么装上来的、 * 能不能自己装、该不该弹窗),这里只负责把 Rust 给的状态说成一句话。 */ -import { textOf } from "@/i18n"; +import { textOf, type Lang } from "@/i18n"; import { updateText } from "./Update.i18n"; /** @@ -18,7 +18,6 @@ export type Install = "homebrew" | "standalone" | "portable" | "dev"; /** 查到的新版本。 */ export interface Found { version: string; - notes?: string | null; } /** 设置页读的那份状态。 */ @@ -33,10 +32,21 @@ export interface UpdateView { export interface Offer extends Found { current: string; install: Install; + notes: ReleaseNotes; /** Homebrew 那一档要执行的命令。由 Rust 给出,界面上不再写一遍 */ command?: string | null; } +export interface ReleaseNotes { + zh: string | null; + en: string | null; +} + +/** 中文界面读中文,其余读英文。旧清单可能缺一份。 */ +export function releaseNotesFor(notes: ReleaseNotes, lang: Lang): string | undefined { + return (lang === "zh" ? notes.zh : notes.en)?.trim() || undefined; +} + /** 按下安装之后走到了哪一步。 */ export type Step = | { step: "downloading" }