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" }