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