CHANGELOG.md is the single source of truth for user-facing release notes. Generate the bilingual entry before creating a release tag:

python3 script/changelog.py upsert \
  --tag v0.10.1 \
  --date 2026-08-01 \
  --notes-file /private/tmp/navop-v0.10.1-release-notes.md \
  --changelog CHANGELOG.md

python3 script/changelog.py extract \
  --tag v0.10.1 \
  --changelog CHANGELOG.md \
  --output /private/tmp/navop-v0.10.1-release-notes-from-changelog.md

git diff -- CHANGELOG.md

Review the extracted Markdown and make sure it matches the source notes, including both ## 中文 and ## English. Commit the changelog entry before creating or pushing the tag.

The normal release sequence is:

1. Generate, review, and commit the target version entry in CHANGELOG.md.
2. Make sure CI passes on the release commit.
3. Create and push the matching v* tag. Both script/release-tag.sh and script/bump-version.sh reject a tag without a valid bilingual changelog entry.
4. Release Trigger dispatches the shared Release workflow on the dev branch.
5. The workflow checks the application version and tagged changelog entry before starting expensive builds.
6. macOS ARM64, macOS x86_64, Linux x86_64, Linux ARM64, and Windows x86_64 build in parallel in one matrix.
7. After all requested platforms finish, the workflow extracts the tagged entry, uses it as the GitHub Release body, and writes the same Markdown to the R2 latest.json release_notes field.

The build workflow checks out the requested tag, while the workflow itself runs from dev. This keeps Cargo input caches and sccache data reusable across tags and repair runs.

The newest entry belongs immediately after the <!-- NAVOP_RELEASES --> marker:

## [v0.10.1] - 2026-08-01

### 中文

#### 更新内容

- ...

#### 修复与优化

- ...

---

### English

#### What's New

- ...

#### Fixes and Improvements

- ...

**Full Changelog**: https://github.com/feigeCode/navop/compare/v0.10.0...v0.10.1

Do not edit generated GitHub or R2 release notes independently for a normal release. Update CHANGELOG.md, create a new tag when appropriate, and let the workflows extract the entry. The extraction tool promotes the entry's headings by one level so the GitHub Release body keeps the established ## 中文 / ## English layout.

Do not move the release tag. Open Actions → Release → Run workflow, enter the existing tag, and select only the failed platform:

The repair run rebuilds only the selected platform, overwrites its assets on the existing GitHub Release, regenerates the complete sha256sums.txt, synchronizes the GitHub Release body from the changelog stored in that tag, and triggers R2 synchronization. Assets from other platforms are preserved.

Tags created before CHANGELOG.md was introduced are treated as legacy repairs: if the GitHub Release already exists, its current body is preserved and reused for R2. A new Release cannot be created from a tag that has neither a tracked changelog entry nor an existing legacy Release body.

For a failed matrix job in the same workflow run, prefer Re-run failed jobs. Successful platform jobs and their workflow artifacts remain available to the final publish job.

• CI, Release, ARM Linux, and the standalone Windows MSI build use the same Cargo registry and Git dependency cache namespace, keyed only by runner OS and Cargo.lock. Linux x86_64 can therefore seed Linux ARM64 inputs, and macOS ARM64 can seed macOS x86_64 inputs.
• Rust compilation uses sccache with the GitHub Actions backend in every Rust build workflow. All five release platforms run from the same default dev workflow scope and reuse compiler objects from earlier runs for the same target and profile.
• The implicit Swatinem/rust-cache inside actions-rust-lang/setup-rust-toolchain is disabled, and target/ is not stored by actions/cache. This avoids duplicating multi-gigabyte target archives that would evict useful sccache objects from GitHub's repository cache quota.
• Release jobs explicitly start sccache and keep it alive through long linking and LTO phases so the final statistics cover the complete build.
• Build caches are shared through workflow runs on the default dev branch instead of being isolated under each release tag.
• ARM Linux uses two Cargo build jobs, thin LTO, and 16 codegen units to reduce peak memory while retaining release optimization.

• Release operations are serialized per tag and are never auto-cancelled.
• A single-platform repair requires the GitHub Release to already exist.
• A new release tag must contain a valid bilingual CHANGELOG.md entry before builds begin.
• GitHub Release notes and R2 updater release_notes are extracted from the same tagged changelog entry.
• Publishing uses --clobber only for newly built platform files and sha256sums.txt.
• Legacy pre-changelog repairs preserve their existing GitHub Release body.
• All five primary platform builds belong to one matrix, so they start in parallel and a failed job can be rerun without rebuilding successful matrix jobs.