sync-changelog
Use after a release succeeds, when maintainers need to sync apps/nori-code/CHANGELOG.md into docs/en/release-notes/changelog.md and docs/zh/release-notes/changelog.md, then open a PR on a dedicated branch.
wangyuahn · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add wangyuahn/nori-code --skill sync-changelog技能说明
name: sync-changelog description: Use after a release succeeds, when maintainers need to sync apps/nori-code/CHANGELOG.md into docs/en/release-notes/changelog.md and docs/zh/release-notes/changelog.md, then open a PR on a dedicated branch.
Sync Changelog
Overview
kimi-code uses changesets for versioning. Each package gets its own CHANGELOG.md. The user-facing CLI package, @moonshot-ai/kimi-code, writes its changelog here:
apps/nori-code/CHANGELOG.md
This file is the only upstream source for the documentation-site changelog. Internal package changelogs such as packages/*/CHANGELOG.md do not go into the documentation site.
After the release flow finishes (Release PR merged → Version Packages completed → npm publish succeeded), maintainers manually run this skill to copy the new CLI changelog entries into the docs site, translate the English increment into Chinese, wait for an optional human review, then commit on a dedicated branch and open a PR.
When To Use
- A new version has been published to npm.
- The top of
apps/nori-code/CHANGELOG.mdcontains version blocks that are not yet indocs/en/release-notes/changelog.md. - The
gen-docsflow does not run this automatically; maintainers must explicitly do it after release.
Do not run this before the Release PR is merged. At that point, changesets has not yet written the new version into apps/nori-code/CHANGELOG.md.
Source And Targets
| File | Role | Edited by |
|---|---|---|
apps/nori-code/CHANGELOG.md | Only upstream source, generated by changesets | Never edit manually |
docs/en/release-notes/changelog.md | English docs changelog; source of truth for docs | This skill |
docs/zh/release-notes/changelog.md | Chinese docs changelog, translated from English | This skill, following translate-docs |
Core rule: the English docs changelog is the source of truth, and Chinese is translated from English. This matches translate-docs.
Preconditions
Before editing, confirm:
- The released version exists on npm (
npm view @moonshot-ai/kimi-code versions --json) or has a matching GitHub Release tag. - The top of
apps/nori-code/CHANGELOG.mdis that new version.
If any condition is not true, stop and confirm with the user.
Do not edit or commit directly on main. All sync work happens on a dedicated branch created in step 1.
Workflow
1. Prepare Branch
Start from an up-to-date default branch:
git fetch origin
git checkout main
git pull --ff-only origin main
Before creating the branch, peek at the version range so the branch name matches the newest version being synced:
rg '^## ' apps/nori-code/CHANGELOG.md | head -5
rg '^## ' docs/en/release-notes/changelog.md | head -5
Name the branch after the newest upstream version that is not yet in the English docs page:
docs/changelog-sync-<newest-version>
Example: syncing 0.2.1 only → docs/changelog-sync-0.2.1.
git checkout -b docs/changelog-sync-<newest-version>
If the branch already exists locally or on the remote, stop and confirm with the user instead of reusing it.
2. Find The Version Range
Use the same version lists from step 1. Confirm:
- First sync: copy all upstream version blocks into the English page.
- Incremental sync: copy every upstream version block above the latest version already present in the English page.
Use upstream order: newest version first.
3. Strip Decorations And Extract Entry Text
Upstream entries look like this:
- [#317](https://github.com/...) [`2f51db4`](https://github.com/...) - Clean up lint warnings ...
Keep:
- Version headings such as
## 0.2.0. - Only the body text of each entry, after the PR/hash decoration.
Remove:
- The upstream H1
# @moonshot-ai/kimi-codebecause the docs page already has# Changelog. - Changesets subheadings such as
### Patch Changes,### Minor Changes, and### Major Changes. - PR links such as
[#317](...). - Commit hash links such as
[`2f51db4`](...).
After stripping, each entry should be only:
- <body text>
Upstream language rule: gen-changesets requires changelog entries to be English. If the upstream CLI changelog contains a non-English entry, stop and report it to the user. Do not silently rewrite it while syncing docs.
Public-text rule: do not copy real internal endpoints, key names, account names, or service names into docs changelogs. Replace examples with neutral placeholders such as example.com, example.test, or YOUR_API_KEY while preserving the user-visible meaning.
4. Classify Entries
The docs changelog uses five section types:
| English section | Chinese section | Meaning |
|---|---|---|
### Features | ### 新功能 | New user-facing functionality, such as a new command, flag, mode, or capability that did not exist before |
### Bug Fixes | ### 修复 | Fixes for behavior that was broken |
### Polish | ### 优化 | User-visible improvements to existing functionality, including UX adjustments, behavior tweaks, and performance improvements that are not fixes or new capabilities |
### Refactors | ### 重构 | Internal changes with no user-visible behavior change, including build, CI, tests, dependency cleanup, and internal renames |
### Other | ### 其他 | Anything that does not fit above, such as CDN/endpoint swaps and docs-related artifacts |
Classification process:
- Classify from the stripped entry text first.
- If unclear, inspect the related commit or PR:
- Use the stripped commit hash with
git show <hash>. - Or use the PR number with
gh pr view <NNN>.
- Use the stripped commit hash with
- If it is still unclear, put it in
Other. Do not guess or force entries intoFeatures.
Features vs. Polish: ask whether the entry introduces something the user could not do before. If yes (new command, flag, mode, viewer, or capability), use Features. If it only improves an existing surface (a UI panel that a