mcpField
W
write-release-notes

write-release-notes

github.com/tldraw文档处理51.1k328 次安装今天更新
代码仓库

关于 write-release-notes

为已发布的 tldraw SDK 版本编写完整发布说明的技能，面向维护者和贡献者。它涵盖 PR 与补丁版本收集、变更分类，以及每项破坏性变更的迁移指南。

主要功能

  1. 01收集版本与合并 PR 信息
  2. 02筛选合入 main 的 PR
  3. 03归纳功能、API 变更和修复
  4. 04为破坏性变更编写迁移指南
  5. 05核验链接、归属和章节顺序

适用场景

  1. 01整理 SDK 版本发布说明
  2. 02汇总某版本的合并 PR
  3. 03记录 API 变更与问题修复
  4. 04为升级者编写迁移步骤

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/tldraw/tldraw --skill write-release-notes

安装后在 Claude Code 中输入/write-release-notes确认已加载。

详细介绍

编写发布说明

本技能介绍如何为已发布的 tldraw SDK 版本撰写一篇完整的发布说明文章。

位置

所有发布文件都位于 apps/docs/content/releases/。

文件用途
next.mdx累积即将发布的版本中的变更
vX.Y.0.mdx已发布的版本（除补丁新增外不可修改）

流程

1. 确定版本

获取版本号并找到 GitHub 发布：

gh release view v4.3.0

这会显示发布日期、标签以及 GitHub 上的任何发布说明。

2. 找出该版本中的所有 PR

列出上一个版本与本版本之间合并的 PR：

# Find commits between releases
git log v4.2.0..v4.3.0 --oneline --merges

# Or use gh to list PRs
gh pr list --state merged --base main --search "merged:2024-01-01..2024-02-01"
3. 获取 PR 详情

对于每个 PR，获取完整详情：

gh pr view <PR_NUMBER> --json title,body,labels,author,baseRefName

关注：

  • PR 正文中的 ### Release notes 部分
  • PR 正文中的 ### API changes 部分
  • 标明类别的标签（api、bugfix、improvement 等）
  • PR 中是否出现 "breaking"

重要： 仅包含 baseRefName 为 main 的 PR。合并到功能分支（例如 default-shape-customization）的 PR 尚未发布——当功能分支本身合并到 main 时它们才会被纳入。

4. 找出补丁版本

列出此次要版本的所有补丁版本：

gh release list | grep "v4.3"

对于每个补丁版本，找出其 PR：

git log v4.3.0..v4.3.1 --oneline --merges
5. 撰写文章

按照风格指南创建 apps/docs/content/releases/vX.Y.0.mdx。

  1. 撰写包含版本、日期和关键词的 frontmatter
  2. 撰写 1-2 句简介，概述亮点
  3. 为主要功能和破坏性变更创建重点章节
  4. 列出 API 变更、改进和缺陷修复
  5. 如适用，添加补丁版本章节
  6. 添加 GitHub 发布链接
6. 为每个破坏性变更撰写迁移指南

文章中的每个 💥 都需要一份迁移方案。tldraw-migrate 技能以这些方案为依据——它有意不在自己的 SKILL.md 中重复它们，因为特定版本的知识应放在引入该变更的破坏性变更旁边。如果方案缺失，执行升级的 Agent 和贡献者就必须从类型定义中逆向推导。

有两种可接受的形式：

对于有自己重点章节的破坏性变更（重命名、被替换的 API、新模式），在该章节下添加一个 <details><summary>Migration guide</summary> 块。包含修改前后的代码，并指出任何静默编译陷阱（类型检查不会拒绝的 props、带有可选新参数的签名等）：

### 💥 Custom themes with display values

[Description of what changed and why]

<details>
<summary>Migration guide</summary>

`getDefaultColorTheme()` and `DefaultColorThemePalette` have been removed. Use `editor.getCurrentTheme().colors[colorMode]` instead:

```tsx
// Before
const theme = getDefaultColorTheme({ isDarkMode })

// After
const theme = editor.getCurrentTheme()
const colors = theme.colors[editor.getColorMode()]
```

</details>

对于 API 变更列表中的单行 💥 条目，条目本身必须包含方案——内联写明替代项及任何注意事项：

  • ✅ 💥 Replace TLDrawShapeSegment.points with the helper getPointsFromDrawSegment(segment, scaleX, scaleY) so segment points respect the shape's current scale.
  • ❌ 💥 Remove TLDrawShapeSegment.points.（无替代项 → 读者只能猜测）

被移除且没有替代项的符号是文档缺陷——找到公开替代项，或者如果确实没有，就明确说明，这样读者就知道应删除调用处，而不是去寻找重命名。

特殊情况——@public → @internal 降级： 这些符号可以编译，但会从公开类型中消失。对于导入了该符号的使用者来说，它们仍是破坏性变更。将其视为移除：用 💥 标记，写明公开替代项，并明确告诉读者不要借助模块扩充来重新暴露被降级的符号。

7. 验证

检查：

  • 所有重要 PR 都已涵盖
  • PR 链接正确且格式规范
  • 社区贡献者已署名
  • 破坏性变更已用 💥 标记
  • 每个 💥 都有迁移指南块或内联替代项（运行 grep -nE '💥' apps/docs/content/releases/<file>.mdx 并逐一核对每个条目/章节）
  • 各章节顺序正确

参考

  • 风格指南: 有关发布说明文章应包含的内容以及如何设置格式的指导，请参阅 ../shared/release-notes-guide.md。

评论

支持 Markdown