Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 12 additions & 5 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 的轻量引用,注解对象根本不在这个克隆里;
Expand All @@ -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 \
Expand All @@ -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" \
Expand Down
42 changes: 20 additions & 22 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -201,28 +201,26 @@ change to `release.yml`, push the branch as `rehearse/<name>`: 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 <version>`; 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 <version>` and written in
English by `scripts/release_notes.py`, in this order:
1. `release-notes/<version>.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 <version>` title and a blank line. It becomes `notes`
in `latest.json`.
- Add the **English summary** at `release-notes/<version>.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 <version>` 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

Expand Down
27 changes: 22 additions & 5 deletions scripts/manifest.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 用的就是它的名字。两处各拼一遍的
Expand All @@ -26,6 +28,8 @@
import pathlib
import sys

from release_notes import NOTES_DIR, NotesError, summary

REPO = "ThinkWatchProject/ThinkWatch-Lite"
# 平台键由更新器自己拼:目标系统 + 架构(macOS 上叫 darwin)。**只收这几个**
# —— 拼错一个字母,那个平台的用户就永远问不到新版本,而清单看起来完好。
Expand Down Expand Up @@ -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"))
Expand Down Expand Up @@ -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")
Expand Down
8 changes: 4 additions & 4 deletions scripts/release_notes.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@

正文是英文的,依次是:

1. `release-notes/<版本>.md`:这一版的说明。**可以没有**,没有就从下载表开始。
1. `release-notes/<版本>.md`:这一版的英文说明。正式发版时必须提供,演练时可省略。
2. 下载表:每个文件一行(Windows 每个架构两行:安装程序、绿色版 zip),文件名和
release.yml 挂上去的一字不差;再给 Homebrew 和 Linux 安装脚本的命令、绿色版的
用法。
Expand All @@ -14,8 +14,8 @@
调用方用 `gh api repos/<仓库>/releases/generate-notes` 取来。拆成参数传进来,
这个脚本就不碰网络,测试可以直接喂它。

**tag 的注解不在这里。**那段中文写进 latest.json(见 manifest.py),是给已经装上
的应用的;发布页面向从网页来下载的人。
应用的英文更新说明也取这份摘要。tag 注解里的中文说明和英文摘要一起写进
latest.json(见 manifest.py)。

说明文件写坏了(有中文、有一级标题、是空的)就不写正文 —— 发版流水线在这一步
停下,比发出去再改好。CI 在每个 PR 上把 `release-notes/` 下的每一份都过一遍
Expand Down Expand Up @@ -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(
Expand Down
21 changes: 21 additions & 0 deletions scripts/release_notes_test.py
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down
65 changes: 57 additions & 8 deletions src-tauri/src/updater.rs
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,25 @@ pub async fn set_update_check(app: tauri::AppHandle, on: bool) -> Out<UpdateView
#[derive(Clone, serde::Serialize)]
pub struct Found {
version: String,
notes: Option<String>,
#[serde(skip_serializing)]
notes: ReleaseNotes,
}

#[derive(Clone, Default, serde::Serialize)]
struct ReleaseNotes {
zh: Option<String>,
en: Option<String>,
}

impl ReleaseNotes {
fn from_manifest(zh: Option<String>, 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 }
}
}

/// 更新在内存里的那点状态。
Expand All @@ -70,7 +88,7 @@ pub struct Updates {
#[derive(serde::Serialize)]
pub struct OfferView {
version: String,
notes: Option<String>,
notes: ReleaseNotes,
current: String,
install: update::Install,
/// Homebrew 那一档要执行的命令。**由这里给出,界面上不再写一遍** ——
Expand All @@ -85,7 +103,7 @@ async fn look(app: &tauri::AppHandle) -> Result<Option<Found>, 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),
}))
}

Expand Down Expand Up @@ -172,7 +190,8 @@ fn brew_offer(version: &str, release: Option<Found>) -> Found {
version: version.to_string(),
notes: release
.filter(|r| r.version == version)
.and_then(|r| r.notes),
.map(|r| r.notes)
.unwrap_or_default(),
}
}

Expand Down Expand Up @@ -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」和别的告知同一个开关:**只在「系统通知」那一档弹**
Expand Down
7 changes: 4 additions & 3 deletions src/UpdateWindow.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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";

Expand Down Expand Up @@ -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<Offer | null>(null);
Expand Down Expand Up @@ -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);
Expand Down
17 changes: 16 additions & 1 deletion src/updateFlow.test.ts
Original file line number Diff line number Diff line change
@@ -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("谁能在窗口里直接装", () => {
/**
Expand Down
Loading
Loading