mirror of
https://github.com/MoonshotAI/kimi-code.git
synced 2026-07-09 17:29:12 +00:00
247 lines
9.5 KiB
Markdown
247 lines
9.5 KiB
Markdown
---
|
|
name: sync-changelog
|
|
description: Use after a release succeeds, when maintainers need to sync apps/kimi-code/CHANGELOG.md into docs/en/release-notes/changelog.md and docs/zh/release-notes/changelog.md.
|
|
---
|
|
|
|
# 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:
|
|
|
|
```text
|
|
apps/kimi-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 and translate the English increment into Chinese.
|
|
|
|
## When To Use
|
|
|
|
- A new version has been published to npm.
|
|
- The top of `apps/kimi-code/CHANGELOG.md` contains version blocks that are not yet in `docs/en/release-notes/changelog.md`.
|
|
- The `gen-docs` flow 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/kimi-code/CHANGELOG.md`.
|
|
|
|
## Source And Targets
|
|
|
|
| File | Role | Edited by |
|
|
|---|---|---|
|
|
| `apps/kimi-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/kimi-code/CHANGELOG.md` is that new version.
|
|
- The current branch is clean, or you are on a dedicated docs-sync branch.
|
|
|
|
If any condition is not true, stop and confirm with the user.
|
|
|
|
## Workflow
|
|
|
|
### 1. Find The Version Range
|
|
|
|
```bash
|
|
# Upstream versions
|
|
rg '^## ' apps/kimi-code/CHANGELOG.md | head -20
|
|
|
|
# Latest version already synced into the English docs page
|
|
rg '^## ' docs/en/release-notes/changelog.md | head -5
|
|
```
|
|
|
|
- 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.
|
|
|
|
### 2. Strip Decorations And Extract Entry Text
|
|
|
|
Upstream entries look like this:
|
|
|
|
```markdown
|
|
- [#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-code` because 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:
|
|
|
|
```markdown
|
|
- <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.
|
|
|
|
### 3. Classify Entries
|
|
|
|
The docs changelog uses four section types:
|
|
|
|
| English section | Chinese section | Meaning |
|
|
|---|---|---|
|
|
| `### Features` | `### 新功能` | New user-facing functionality |
|
|
| `### Bug Fixes` | `### 修复` | Fixes for behavior that was broken |
|
|
| `### 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 user-visible adjustments that are not fixes or features, CDN/endpoint swaps, and docs-related artifacts |
|
|
|
|
Classification process:
|
|
|
|
1. Classify from the stripped entry text first.
|
|
2. 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>`.
|
|
3. If it is still unclear, put it in `Other`. Do not guess or force entries into `Features`.
|
|
|
|
Keyword hints:
|
|
|
|
- **Features**: `Add`, `Introduce`, `Support`, `Allow`, `Enable`, `Implement`, `New ... command/flag/option`
|
|
- **Bug Fixes**: `Fix`, `Resolve`, `Correct`, `Address`, `Prevent ... from`, `Stop ... from`, `... no longer ...`
|
|
- **Refactors**: `Refactor`, `Rename`, `Clean up`, `Simplify`, `Remove unused`, `Migrate to`, `Unify`, `Restructure`, `Internal`, dependency bumps, pure CI/build/test changes
|
|
- **Other**: docs artifacts, CDN/endpoint switches, or small user-visible adjustments that are not fixes or new features
|
|
|
|
Within each version, section order is:
|
|
|
|
```text
|
|
Features → Bug Fixes → Refactors → Other
|
|
```
|
|
|
|
Omit empty sections. Preserve upstream entry order within each section.
|
|
|
|
### 4. Write The English Page
|
|
|
|
Never change the English page header:
|
|
|
|
```markdown
|
|
# Changelog
|
|
|
|
This page documents the changes in each Kimi Code CLI release.
|
|
```
|
|
|
|
Insert new version blocks immediately after the header paragraph and before the previous latest version.
|
|
|
|
Example:
|
|
|
|
```markdown
|
|
## 0.2.0
|
|
|
|
### Bug Fixes
|
|
|
|
- Fix the TUI not restoring the current todo list after resuming a session.
|
|
|
|
### Refactors
|
|
|
|
- Clean up lint warnings across the CLI, SDK examples, and bundled runtime code without changing product behavior.
|
|
- Update the native release workflow to use current GitHub artifact actions.
|
|
```
|
|
|
|
### 5. Translate The Increment Into Chinese
|
|
|
|
After updating the English page, translate only the newly added English content into `docs/zh/release-notes/changelog.md`.
|
|
|
|
Follow `translate-docs`, direction `en → zh`. Changelog direction is English-to-Chinese even though many other docs flows use Chinese-to-English.
|
|
|
|
Chinese page requirements:
|
|
|
|
- Header:
|
|
|
|
```markdown
|
|
# 变更记录
|
|
|
|
本页记录 Kimi Code CLI 每个版本的变更内容。
|
|
```
|
|
|
|
- Preserve version headings exactly, such as `## 0.2.0`.
|
|
- Translate section headings exactly:
|
|
- `### Features` → `### 新功能`
|
|
- `### Bug Fixes` → `### 修复`
|
|
- `### Refactors` → `### 重构`
|
|
- `### Other` → `### 其他`
|
|
- The Chinese page must mirror the English page 1:1 for versions, sections, section order, and entry counts.
|
|
- Keep the classification from the English page. Do not reclassify while translating.
|
|
- Translate only entry body text. Do not add entries that are not present in English.
|
|
- Follow `docs/AGENTS.md` for Chinese typography: full-width punctuation, spaces between Chinese and English, and the glossary.
|
|
|
|
### 6. Verify
|
|
|
|
Review:
|
|
|
|
```bash
|
|
git diff docs/en/release-notes/changelog.md docs/zh/release-notes/changelog.md
|
|
```
|
|
|
|
Check:
|
|
|
|
- Versions and version counts match between English and Chinese.
|
|
- Each version has the same section set and order on both pages.
|
|
- Each section has the same number of entries on both pages.
|
|
- PR links and commit hashes were stripped.
|
|
- There are no empty sections.
|
|
- Markdown indentation and blank lines are intact.
|
|
|
|
Then run the docs build:
|
|
|
|
```bash
|
|
pnpm --filter docs run build
|
|
```
|
|
|
|
### 7. Commit
|
|
|
|
Use a neutral docs-sync commit message:
|
|
|
|
```text
|
|
docs(changelog): sync <version range> from apps/kimi-code/CHANGELOG.md
|
|
```
|
|
|
|
Do **not** create a changeset for changelog docs sync. Docs sync does not enter the bundle.
|
|
|
|
## Rules
|
|
|
|
- The English docs changelog is the source of truth.
|
|
- Never edit upstream `apps/kimi-code/CHANGELOG.md`.
|
|
- Do not backfill unreleased `.changeset/*.md` drafts into the docs site.
|
|
- If upstream wording is wrong, leave upstream alone and fix it in a future changeset.
|
|
|
|
## Common Mistakes
|
|
|
|
| Mistake | Fix |
|
|
|---|---|
|
|
| Adding entries directly to the English docs page without reading upstream | Use `apps/kimi-code/CHANGELOG.md` as the source |
|
|
| Copying PR links or commit hashes into docs | Strip them; keep only body text |
|
|
| Rewording upstream English entries | Upstream is frozen; copy the body text unless the user explicitly asks otherwise |
|
|
| Leaving English text untranslated in the Chinese page | The Chinese page must be fully Chinese except preserved technical terms |
|
|
| Editing upstream changelog text | Do not edit upstream |
|
|
| Losing two-space indentation in multi-line list items | Restore indentation so Markdown lists stay valid |
|
|
| Copying `### Patch Changes` into docs | Remove changesets headings and classify under Features / Bug Fixes / Refactors / Other |
|
|
| Guessing unclear entries as Features | Inspect commit/PR; if still unclear, use Other |
|
|
| Reclassifying entries while translating | Chinese classification must mirror English |
|
|
| Leaving empty sections | Delete sections with no entries |
|
|
| Putting everything under Other for convenience | Classify what can be classified first |
|
|
| Translating tool names, command names, or config keys | Keep them as written |
|
|
| Creating a changeset for docs sync | Do not create one |
|
|
| Using curly quotes or half-width Chinese punctuation | Follow `docs/AGENTS.md` |
|
|
|
|
## Stop Signals
|
|
|
|
- The top version in `apps/kimi-code/CHANGELOG.md` is not published on npm or GitHub Releases.
|
|
- You are about to edit `apps/kimi-code/CHANGELOG.md`.
|
|
- You are about to add docs sync to a changeset.
|
|
- English and Chinese versions, entry counts, or section sets do not match.
|
|
- A section is empty.
|
|
- A Chinese term is uncertain and `docs/AGENTS.md` does not answer it.
|