Navop Release Notes

Overview

Maintain Navop's repository-root CHANGELOG.md as the single source of truth for user-facing release notes. Generate a bilingual entry before creating the version tag. The Release workflows extract that tagged entry to set both the GitHub Release body and the R2 updater manifest's release_notes.

Do not treat GitHub or R2 as the primary editing surface. For a normal release, update and review CHANGELOG.md, commit it, and only then create the tag. Only edit an existing GitHub Release directly when the user explicitly asks for a manual synchronization or repair.

Required Context

Work from the Navop repo root and confirm the remote points to feigeCode/navop:

rtk git status --short --branch
rtk git remote -v
rtk git tag --sort=-creatordate
rtk gh release list --limit 8

Confirm all four release inputs:

• Target version tag, for example v0.10.1.
• Previous version tag, for example v0.10.0.
• Source ref containing the release changes: normally HEAD before tagging, or the target tag after it exists.
• ISO release date, for example 2026-08-01.

If the user names versions, use those exact versions. Otherwise infer the previous tag from the newest stable version tag, but do not invent the target version. Never create a tag, commit, push, or publish unless the user explicitly requested that operation.

Before writing notes, inspect recent Release style. Read the target Release only if it already exists:

rtk gh release view <previous-tag> --json tagName,name,body,publishedAt,url
rtk gh release view <older-tag> --json tagName,name,body,publishedAt,url
rtk gh release view <target-tag> --json tagName,name,body,publishedAt,url # existing release/repair only

If Navop has no established Release style yet, use this bilingual shape. Entries carry no ## 中文 / ## English language headings; each entry must include the CNB mirror download line:

### 更新内容

- ...

### 修复与优化

- ...

国内下载：如果 GitHub 下载较慢，可从 [CNB 镜像](https://cnb.cool/navop-dev/navop/-/releases/tag/<target-tag>) 下载桌面端安装包

---

### What's New

- ...

### Fixes and Improvements

- ...

**Full Changelog**: https://github.com/feigeCode/navop/compare/<previous-tag>...<target-tag>

For larger releases, add short overview paragraphs and extra sections only when prior style or commit volume justifies it.

Generate Notes

Read commits and changed files:

TARGET_REF=HEAD # or the existing target tag
rtk git log --reverse --format='%H%n%s%n%b%n---END---' <previous-tag>.."$TARGET_REF"
rtk git diff --stat <previous-tag>.."$TARGET_REF"
rtk git diff --name-status <previous-tag>.."$TARGET_REF"

For unclear commits, inspect targeted diffs:

rtk git show --stat --oneline --find-renames <commit>
rtk git show --format=medium --find-renames <commit> -- <path>

Summarize user-facing behavior, not implementation trivia. Use categories:

• Chinese 更新内容: features, UX improvements, performance, workflow improvements.
• Chinese 修复与优化: bug fixes, compatibility, stability, maintenance with user impact.
• English What's New: faithful English version of 更新内容.
• English Fixes and Improvements: faithful English version of 修复与优化.

Include maintenance bullets only when visible in commits and useful to release readers. Keep internal refactors out unless they explain a visible behavior change.

Prepare The Changelog Entry

Save the generated body to a temporary Markdown file first. Prefer /private/tmp on this machine:

NOTES=/private/tmp/navop-<target-tag>-release-notes.md

Create the file with normal editing tools, then review it:

rtk sed -n '1,240p' /private/tmp/navop-<target-tag>-release-notes.md

The notes file is incomplete unless every one of these items is present. Check each one before continuing:

• At least one Chinese content section (### 更新内容 or ### 修复与优化)
• At least one English content section (### What's New or ### Fixes and Improvements)
• The CNB mirror download line, using the exact target tag (hard requirement, easy to forget):

  国内下载：如果 GitHub 下载较慢，可从 [CNB 镜像](https://cnb.cool/navop-dev/navop/-/releases/tag/<target-tag>) 下载桌面端安装包
  

• The final compare link must use three dots:

**Full Changelog**: https://github.com/feigeCode/navop/compare/<previous-tag>...<target-tag>

Run grep -F "cnb.cool/navop-dev/navop/-/releases/tag/<target-tag>" "$NOTES" and fail the entry if it returns nothing.

**Full Changelog**: https://github.com/feigeCode/navop/compare/<previous-tag>...<target-tag>

Upsert the reviewed body into CHANGELOG.md:

python3 script/changelog.py upsert \
  --tag <target-tag> \
  --date <YYYY-MM-DD> \
  --notes-file "$NOTES" \
  --changelog CHANGELOG.md

The tool inserts the newest version after <!-- NAVOP_RELEASES -->, preserves older entries, and replaces an existing target entry idempotently.

Extract it back before approving the entry:

EXTRACTED=/private/tmp/navop-<target-tag>-release-notes-from-changelog.md
python3 script/changelog.py extract \
  --tag <target-tag> \
  --changelog CHANGELOG.md \
  --output "$EXTRACTED"

diff -u "$NOTES" "$EXTRACTED"
rtk git diff -- CHANGELOG.md

The extracted file must match the generated body. Small newline-only differences can be normalized, but content, headings, ordering, and compare URL must be identical.

Commit the reviewed changelog before tagging. script/release-tag.sh and script/bump-version.sh validate the target entry and fail before tagging if it is missing or malformed.

Workflow Publishing

For normal releases, do not run gh release edit yourself:

1. The Release workflow checks out the requested tag.
2. script/changelog.py extract produces the GitHub Release body.
3. The same extracted Markdown is added to R2 updates/latest.json as release_notes.
4. The application renders either GitHub's Release body or R2's release_notes, depending on the selected update source.

Tags older than the changelog infrastructure are legacy-only. Repair workflows may preserve an already-existing GitHub Release body, but they must not create a new changelog-less Release.

Manual Synchronization

Only when explicitly asked to synchronize an existing GitHub Release, extract from CHANGELOG.md first and use that file:

EXTRACTED=/private/tmp/navop-<target-tag>-release-notes-from-changelog.md
python3 script/changelog.py extract \
  --tag <target-tag> \
  --changelog CHANGELOG.md \
  --output "$EXTRACTED"

rtk gh release edit <target-tag> \
  --title "Navop <target-tag>" \
  --notes-file "$EXTRACTED"

Do not compose a different body directly in GitHub. If the desired text changes, update CHANGELOG.md first.

Verify

Always validate the local entry:

python3 script/changelog.py validate \
  --tag <target-tag> \
  --changelog CHANGELOG.md

If a GitHub Release was published or synchronized, run a fresh read:

rtk gh release view <target-tag> --json tagName,name,body,publishedAt,url

Verify:

• tagName is the intended target tag.
• body contains the Chinese 更新内容 and English What's New sections, the CNB mirror download line, and the expected compare URL.
• The visible content matches the file extracted from CHANGELOG.md.

If R2 was published, read its public updater manifest and verify:

• version matches the target tag without the leading v.
• release_notes contains the same Chinese and English Markdown.
• Download URLs and checksums remain present.

Also check the working tree so unrelated local edits are not mistaken for release-note work:

rtk git status --short --branch

Report the changed changelog entry, whether it was committed/tagged/published, and the verification result. Never claim GitHub or R2 was updated unless a fresh remote read confirms it.

Common Mistakes

Mistake	Correct Action
Using only Chinese notes	Publish matching Chinese and English sections.
Omitting the CNB mirror download line	Every entry must include the 国内下载 / CNB mirror line pointing at the exact target tag; grep the notes file for it before continuing.
Creating the tag before the changelog	Generate, review, and commit the target CHANGELOG.md entry first.
Editing GitHub and changelog separately	Treat CHANGELOG.md as authoritative and extract the GitHub body from it.
Omitting R2 notes	Confirm latest.json.release_notes is populated from the same extracted entry.
Assuming legacy repository details	Confirm the remote is feigeCode/navop and use Navop URLs, titles, and temp-file names.
Comparing the wrong tags	Confirm newest two tags or use user-specified tags before writing.
Listing raw commits	Group commits into release-reader categories.
Replacing a legacy Release accidentally	Only use the legacy fallback for an already-existing pre-changelog Release.
Claiming saved without verification	Validate locally and re-read each remote destination that was actually published.