Back to Details

write-release-notes

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Write release notes

撰写发布说明

This skill covers how to write a complete release notes article for a published tldraw SDK release.
本指南介绍如何为已发布的tldraw SDK版本撰写完整的发布说明文档。

Location

文件位置

All release files live in 
apps/docs/content/releases/
.
FilePurpose
next.mdx
Accumulates changes for the upcoming release
vX.Y.0.mdx
Published releases (immutable except for patch additions)
所有发布文件都存放在
apps/docs/content/releases/
目录下。
文件用途
next.mdx
累积即将发布版本的变更内容
vX.Y.0.mdx
已发布的版本（除补丁更新外不可修改）

Process

操作流程

1. Identify the release

1. 确定版本信息

Get the version number and find the GitHub release:
bash
gh release view v4.3.0
This shows the release date, tag, and any release notes from GitHub.
获取版本号并找到对应的GitHub版本：
bash
gh release view v4.3.0
这会显示版本发布日期、标签以及GitHub上的所有发布说明。

2. Find all PRs in the release

2. 找出版本中的所有PR

List PRs merged between the previous release and this one:
bash
undefined
列出上一个版本到当前版本之间合并的PR：
bash
undefined

Find commits between releases

Find commits between releases

git log v4.2.0..v4.3.0 --oneline --merges
git log v4.2.0..v4.3.0 --oneline --merges

Or use gh to list PRs

Or use gh to list PRs

gh pr list --state merged --base main --search "merged:2024-01-01..2024-02-01"
undefined
gh pr list --state merged --base main --search "merged:2024-01-01..2024-02-01"
undefined

3. Fetch PR details

3. 获取PR详情

For each PR, get the full details:
bash
gh pr view <PR_NUMBER> --json title,body,labels,author
Look for:
  • ### Release notes
    section in PR body
  • ### API changes
    section in PR body
  • Labels indicating category (api, bugfix, improvement, etc.)
  • Whether "breaking" appears in the PR
针对每个PR，获取完整详情：
bash
gh pr view <PR_NUMBER> --json title,body,labels,author
重点关注：
  • PR正文中的
    ### Release notes
    部分
  • PR正文中的
    ### API changes
    部分
  • 标明分类的标签（api、bugfix、improvement等）
  • PR中是否包含“breaking”（破坏性变更）相关内容

4. Find patch releases

4. 查找补丁版本

List any patch releases for this minor version:
bash
gh release list | grep "v4.3"
For each patch release, find its PRs:
bash
git log v4.3.0..v4.3.1 --oneline --merges
列出该小版本下的所有补丁版本：
bash
gh release list | grep "v4.3"
针对每个补丁版本，找出对应的PR：
bash
git log v4.3.0..v4.3.1 --oneline --merges

5. Write the article

5. 撰写文档

Create 
apps/docs/content/releases/vX.Y.0.mdx
following the style guide.
  1. Write the frontmatter with version, dates, and keywords
  2. Write a 1-2 sentence introduction summarizing highlights
  3. Create featured sections for major features and breaking changes
  4. List API changes, improvements, and bug fixes
  5. Add patch release sections if applicable
  6. Add GitHub release links
按照风格指南创建
apps/docs/content/releases/vX.Y.0.mdx
文件。
  1. 编写包含版本号、日期和关键词的前置元数据
  2. 撰写1-2句话的引言，概述版本亮点
  3. 为主要功能和破坏性变更创建特色板块
  4. 列出API变更、功能改进和Bug修复内容
  5. 如有需要，添加补丁版本板块
  6. 添加GitHub版本链接

6. Verify

6. 验证内容

Check that:
  • All significant PRs are represented
  • PR links are correct and formatted properly
  • Community contributors are credited
  • Breaking changes are marked with 💥
  • Sections are in the correct order
检查以下内容：
  • 所有重要PR都已涵盖
  • PR链接正确且格式规范
  • 已致谢社区贡献者
  • 破坏性变更已标记💥
  • 板块顺序正确

References

参考资料

  • Style guide: See 
    ../shared/release-notes-guide.md
    for guidance on what a release notes article should contain and how to format it.
  • 风格指南：查看
    ../shared/release-notes-guide.md
    ，了解发布说明文档应包含的内容及格式规范。