技能分享变更日志
- 作者仓库星标 194
- 作者仓库 skills
- 领域
- 通用
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @JetBrains · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 即装即用
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
第 8 步:发布说明(仅限维护人员)
`specs/RELEASE_NOTES_<version>.md`仅当用户是项目维护者(runkids)时生成。贡献者跳过此步骤。检查是否以维护者身份运行: 如果是维护者: 阅读最新的`specs/RELEASE_NOTES_*.md`作为样式参考生成`specs/RELEASE_NOTES_<version>.md`(不`v`前缀,例如`RELEASE_NOTES_0.17.6.md`)
Generate a CHANGELOG.md entry for a release. $ARGUMENTS specifies the tag version (e.g., `v0.16.0`) or omit to auto-detect via `git describe --tags --abbrev=0`.
**Scope**: This skill updates `CHANGELOG.md` and syncs the website changelog (`website/src/pages/changelog.md`). It does NOT write code (use `implement-feature`) or update docs (use `update-docs`).
## Workflow
### Step 1: Determine Version Range
```bash
# Auto-detect latest tag
LATEST_TAG=$(git describe --tags --abbrev=0)
# Find previous tag
PREV_TAG=$(git describe --tags --abbrev=0 "${LATEST_TAG}^")
echo "Generating changelog: $PREV_TAG → $LATEST_TAG"
```
### Step 2: Collect Commits
```bash
git log "${PREV_TAG}..${LATEST_TAG}" --oneline --no-merges
```
### Step 3: Categorize Changes
Group commits by conventional commit type:
| Prefix | Category |
|--------|----------|
| `feat` | New Features |
| `fix` | Bug Fixes |
| `refactor` | Refactoring |
| `docs` | Documentation |
| `perf` | Performance |
| `test` | Tests |
| `chore` | Maintenance |
### Step 4: Read Existing Entries for Style Reference
Before writing, read the most recent 2-3 entries in `CHANGELOG.md` to match the established tone and structure. The style evolves over time — always match the latest entries, not a hardcoded template.
### Step 5: Write User-Facing Entry
Write from the **user's perspective**. Only include changes users will notice or care about.
**Include**:
- New features with usage examples (CLI commands, code blocks)
- Bug fixes that affected user-visible behavior
- Breaking changes (renames, removed flags, scope changes)
- Performance improvements users would notice
**Exclude**:
- Internal test changes (smoke tests, test refactoring)
- Implementation details (error propagation, internal structs)
- Dev toolchain changes (Makefile cleanup, CI tweaks)
- Pure documentation adjustments
**Wording guidelines**:
- Don't use "first-class", "recommended" for non-default options
- Be factual: "Added X" / "Fixed Y" / "Renamed A to B"
- Include CLI example when introducing a new feature
- Use em-dash (`—`) to separate feature name from description
- Group related features under `####` sub-headings when there are 2+ distinct areas
### Step 6: Update CHANGELOG.md
Read existing `CHANGELOG.md` and insert new entry at the top, after the header. Match the style of the most recent entries exactly.
Structural conventions (based on actual entries):
```markdown
## [X.Y.Z] - YYYY-MM-DD
### New Features
#### Feature Area Name
- **Feature name** — description with `inline code` for commands and flags
```bash
skillshare command --flag # usage example
```
Additional context as sub-bullets or continuation text
#### Another Feature Area
- **Feature name** — description
### Bug Fixes
- Fixed specific user-visible behavior — with context on what changed
- Fixed another issue
### Performance
- **Improvement name** — description of what got faster
### Breaking Changes
- Renamed `old-name` to `new-name`
```
Key style points:
- Version numbers use `[X.Y.Z]` without `v` prefix in the heading
- Feature bullets use `**bold name** — em-dash description` format
- Code blocks use `bash` language tag for CLI examples
- Bug fixes describe the symptom, not the implementation
- Only include sections that have content (skip empty Performance, Breaking Changes, etc.)
### Step 7: Sync Website Changelog
The website has its own changelog page at `website/src/pages/changelog.md`. After updating `CHANGELOG.md`, sync the new entry to the website version.
**Differences between the two files**:
- Website file has MDX frontmatter (`title`, `description`) and an intro paragraph — preserve these, don't overwrite
- Website file has a `---` separator after the intro, before the first version entry
- The release entries themselves are identical in content
**How to sync**: Read the website changelog, then insert the same new entry after the `---` separator (line after intro paragraph), before the first existing version entry. Do NOT replace the entire file — only insert the new entry block.
### Step 8: RELEASE_NOTES (Maintainer Only)
`specs/RELEASE_NOTES_<version>.md` is only generated when the user is the project maintainer (runkids). Contributors skip this step.
Check if running as maintainer:
```bash
git config user.name # Should match maintainer identity
```
If maintainer:
- Read the most recent `specs/RELEASE_NOTES_*.md` as a style reference
- Generate `specs/RELEASE_NOTES_<version>.md` (no `v` prefix, e.g. `RELEASE_NOTES_0.17.6.md`)
- Structure:
- Title: `# skillshare vX.Y.Z Release Notes`
- TL;DR section with numbered highlights
- One `##` section per feature/fix — describe **what changed** in plain language, with a CLI example or code block if relevant. No "The problem / Solution" structure — just state what it does now
- Include migration guide if breaking changes exist
**RELEASE_NOTES wording rules** (same user-facing standard as CHANGELOG):
- Describe **what changed** from the user's perspective, not how the code changed
- **Never mention**: function names, variable names, struct fields, file paths, Go syntax, internal APIs
- ✅ Good: "Sync now auto-creates missing target directories and shows what it did"
- ❌ Bad: "upgraded `Server.mu` from `sync.Mutex` to `sync.RWMutex` and applied a snapshot pattern across 30 handlers"
- Keep it concise — a short paragraph per feature is enough, no need for multi-section breakdowns
If not maintainer:
- Skip RELEASE_NOTES generation
- Only update CHANGELOG.md + website changelog
## Rules
- **User perspective** — write for users, not developers
- **No fabricated links** — never invent URLs or references
- **Verify features exist** — grep source before claiming a feature was added
- **No internal noise** — exclude test-only, CI-only, or refactor-only changes
- **Conventional format** — follow existing CHANGELOG.md style exactly
- **Always sync both** — `CHANGELOG.md` and `website/src/pages/changelog.md` must have identical release entries
- **RELEASE_NOTES = maintainer only** — contributors only update CHANGELOG.md + website changelog
章节与文件索引
按说明文件中的顺序排列。
第 3 步:对变更进行分类
第 4 步:阅读现有条目以获取样式参考
第 5 步:编写面向用户的条目
第6步:更新CHANGELOG.md
第 7 步:同步网站变更日志
文件/命令 -> v0.16.0 · git describe --tags --abbrev=0 · CHANGELOG.md · website/src/pages/changelog.md · implement-feature · update-docs · feat · fix
内容校验值 -> 29a9cf2ccd20
当前原文的自动摘译,尚未人工审校。
第 3 步:对变更进行分类
按常规提交类型对提交进行分组:前缀·类别
feat· 新功能fix· 错误修复refactor· 重构第 4 步:阅读现有条目以获取样式参考
在写作之前,请阅读以下最新的 2-3 条内容:
CHANGELOG.md以匹配既定的语气和结构。风格随着时间的推移而演变——始终匹配最新的条目,而不是硬编码的模板。第 5 步:编写面向用户的条目
从用户的角度来写。仅包含用户会注意到或关心的更改。包括: 新功能和使用示例(CLI 命令、代码块) 影响用户可见行为的错误修复 重大更改(重命名、删除标志、范围更改)
第6步:更新CHANGELOG.md
阅读现有的
CHANGELOG.md并在标题后面的顶部插入新条目。与最新条目的风格完全匹配。结构约定(以实际条目为准):skillshare 命令 --flag # 用法示例 风格要点:版本号使用[X.Y.Z]没有v标题中的前缀第 7 步:同步网站变更日志
该网站有自己的变更日志页面:
website/src/pages/changelog.md。更新后CHANGELOG.md,将新条目同步到网站版本。两个文件之间的区别: 网站文件有 MDX frontmatter (title,description)和一个介绍段落 - 保留这些,不要覆盖网站文件有一个---简介之后、第一个版本条目之前的分隔符 发行条目本身的内容相同