release-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Release Workflow for ai-todo

ai-todo 发布工作流

Quick Reference

快速参考

Prepare:

./release/release.sh --prepare [--beta] [--set-version X.Y.Z] --summary release/AI_RELEASE_SUMMARY.md

Dry Run:

./release/release.sh --prepare --dry-run

(preview without committing)

Execute:
```
./release/release.sh --execute
```
Abort:
```
./release/release.sh --abort [version]
```
(cleanup failed release)
Linear Tracking: Release workflow integrated with Linear issues (auto-updates status)
Detailed docs: release/RELEASE_PROCESS.md

准备：

./release/release.sh --prepare [--beta] [--set-version X.Y.Z] --summary release/AI_RELEASE_SUMMARY.md

试运行：
```
./release/release.sh --prepare --dry-run
```
（无需提交即可预览效果）
执行：
```
./release/release.sh --execute
```
中止：
```
./release/release.sh --abort [version]
```
（清理失败的发布）
Linear 跟踪： 发布工作流与 Linear issue 集成（自动更新状态）
详细文档： release/RELEASE_PROCESS.md

Prepare a Release

准备发布

When user asks to "prepare release" or "prepare beta release":

Check Linear for release issue:
- Search Linear for release-related issues:
```
user-linear.list_issues
```
  with filters for release keywords
- If no issue found: ⚠️ Warn "No Linear release issue found. Do you want to proceed anyway?"
- If one issue found: Show issue details and confirm
- If multiple issues found: Present list and ask user to select one
- Once confirmed: Mark issue as "In Progress" using
```
user-linear.update_issue
```
- Store issue ID for later updates
Pre-flight checks: Verify repository is ready for release:
- Check branch:
```
git branch --show-current
```
  (must be
```
main
```
  )
- Check sync:
```
git fetch origin && git status
```
  (must be in sync with origin/main)
- Check clean:
```
git status --porcelain
```
  (must be empty - no uncommitted changes)
- If any check fails: ⚠️ Warn user with specific issue and ask "Do you want to proceed anyway?"
- If user declines: Stop and let them fix the issue first.
Wait for CI:
```
./scripts/wait-for-ci.sh
```
Generate summary: Create 2-4 paragraphs highlighting user-facing changes. Save to
```
release/AI_RELEASE_SUMMARY.md
```
.
- For beta-to-beta releases: Analyze commits since the last beta tag.
- For stable releases (graduating from beta): Analyze ALL commits since the last stable release (not the last beta). This ensures the summary covers the entire beta cycle.
- See "Generating Release Summary" section below for detailed guidance.

Commit and push summary: The release script requires a clean repository.

```
git add release/AI_RELEASE_SUMMARY.md
```

git commit -m "release: Add AI-generated summary for v[version]"

```
git push
```

Run prepare:

./release/release.sh --prepare [--beta] --summary release/AI_RELEASE_SUMMARY.md

Show preview to user: Display the proposed release notes with clickable link.
- Show
```
release/RELEASE_NOTES.md
```
  summary/preview (first ~20 lines)
- Provide clickable markdown link:
```
[release/RELEASE_NOTES.md](release/RELEASE_NOTES.md)
```
  (not inline code)

Update Linear issue:

Read
```
release/RELEASE_NOTES.md
```
content
Post content to Linear issue as comment using
```
user-linear.create_comment
```

Include clickable link: Add link to full notes at top of comment:

📋 Full Release Notes: [release/RELEASE_NOTES.md](https://github.com/fxstein/ai-todo/blob/main/release/RELEASE_NOTES.md)

Mark issue as "In Review" using
```
user-linear.update_issue
```

STOP. Wait for user approval before proceeding.

当用户要求「准备发布」或「准备测试版发布」时：

在 Linear 中检查发布相关 issue：
- 搜索 Linear 中与发布相关的 issue：调用
```
user-linear.list_issues
```
  并使用发布关键词过滤
- 未找到相关 issue： ⚠️ 提示「未找到 Linear 发布相关 issue，是否仍要继续？」
- 找到1个相关 issue： 展示 issue 详情并请用户确认
- 找到多个相关 issue： 展示列表请用户选择其中一个
- 确认后： 调用
```
user-linear.update_issue
```
  将 issue 标记为「进行中」
- 存储 issue ID 用于后续更新
发布前检查： 验证代码仓库已就绪可发布：
- 检查分支：
```
git branch --show-current
```
  （必须是
```
main
```
  分支）
- 检查同步状态：
```
git fetch origin && git status
```
  （必须与 origin/main 保持同步）
- 检查工作区清洁度：
```
git status --porcelain
```
  （必须无输出，即没有未提交的变更）
- 任意检查未通过： ⚠️ 告知用户具体问题并询问「是否仍要继续？」
- 用户选择不继续： 终止流程，让用户先修复问题
等待 CI 运行完成：
```
./scripts/wait-for-ci.sh
```
生成发布摘要： 撰写2-4段突出面向用户变更的内容，保存到
```
release/AI_RELEASE_SUMMARY.md
```
- 测试版到测试版的发布： 分析上一个测试版标签之后的所有提交
- 正式版发布（从测试版转正）： 分析上一个正式版之后的所有提交（而非上一个测试版），确保摘要覆盖整个测试周期的内容
- 参考下文「生成发布摘要」章节获取详细指导

提交并推送摘要： 发布脚本要求工作区处于清洁状态

```
git add release/AI_RELEASE_SUMMARY.md
```

git commit -m "release: Add AI-generated summary for v[version]"

```
git push
```

运行准备命令：

./release/release.sh --prepare [--beta] --summary release/AI_RELEASE_SUMMARY.md

向用户展示预览： 展示拟发布的 Release Notes 及可点击链接
- 展示
```
release/RELEASE_NOTES.md
```
  的摘要/预览（前20行左右）
- 提供可点击的 Markdown 链接：
```
[release/RELEASE_NOTES.md](release/RELEASE_NOTES.md)
```
  （不要使用行内代码格式）

更新 Linear issue：

读取
```
release/RELEASE_NOTES.md
```
内容
调用
```
user-linear.create_comment
```
将内容作为评论发布到 Linear issue

添加可点击链接： 在评论顶部添加完整笔记的链接：

📋 完整 Release Notes: [release/RELEASE_NOTES.md](https://github.com/fxstein/ai-todo/blob/main/release/RELEASE_NOTES.md)

调用
```
user-linear.update_issue
```
将 issue 标记为「审核中」

停止流程，等待用户批准后再继续后续操作

Generating Release Summary

生成发布摘要

Role: You are a Technical Release Manager for a professional Open Source project.

Task: Draft a release summary based on commit messages for end-users (not developers).

Commit Range:

For beta-to-beta releases: Analyze commits since the last beta tag (e.g.,
```
v4.0.0b2..HEAD
```
)
For stable releases (graduating from beta): Analyze ALL commits since the last stable release (e.g.,
```
v3.0.2..HEAD
```
)

Constraints & Formatting:

Format: Write exactly 2-4 paragraphs of narrative text. Do not use bulleted lists or markdown headers (e.g., no
```
#
```
or
```
##
```
).
Content: Focus only on the most significant features, user-facing changes, and critical fixes. Filter out minor chores, typo fixes, or internal refactors unless they directly impact end users.
Documentation: If commits added new documentation files (
```
.md
```
,
```
.pdf
```
), mention them with direct GitHub links:
- Get repo URL:
```
git remote get-url origin
```
  (convert SSH to HTTPS if needed)
- Format:
```
[filename](https://github.com/user/repo/blob/main/path/to/file.md)
```
Tone: Professional, concise, and encouraging. Write for users who want to understand what's new and why they should upgrade.
Output: Save to
```
release/AI_RELEASE_SUMMARY.md
```

Example Structure:

This release focuses on [theme/primary improvement]. [Key feature 1] provides [user benefit]. [Key feature 2] enhances [capability].

[Second major area of improvement]. [Specific change] now allows users to [benefit]. [Another change] improves [aspect] by [improvement].

Additional improvements include [grouped minor features]. Several bug fixes improve robustness including [specific fixes that matter to users].

Generate Commits:

bash

undefined

角色： 你是专业开源项目的技术发布经理

任务： 基于提交信息为终端用户（而非开发人员）撰写发布摘要

提交范围：

测试版到测试版的发布： 分析上一个测试版标签之后的提交（例如
```
v4.0.0b2..HEAD
```
）
正式版发布（从测试版转正）： 分析上一个正式版之后的所有提交（例如
```
v3.0.2..HEAD
```
）

约束与格式要求：

格式： 严格撰写2-4段叙述性文本，不要使用无序列表或 Markdown 标题（即不要使用
```
#
```
或
```
##
```
）
内容： 仅聚焦最重要的功能、面向用户的变更和关键修复。过滤掉次要的琐事、拼写修复或内部重构，除非这些变更直接影响终端用户
文档： 如果提交新增了文档文件（
```
.md
```
、
```
.pdf
```
），需附上对应的 GitHub 直链：
- 获取仓库地址：
```
git remote get-url origin
```
  （如果是 SSH 格式请转换为 HTTPS 格式）
- 格式：
```
[filename](https://github.com/user/repo/blob/main/path/to/file.md)
```
语气： 专业、简洁、积极，面向希望了解新功能和升级价值的用户撰写
输出： 保存到
```
release/AI_RELEASE_SUMMARY.md
```

示例结构：

This release focuses on [theme/primary improvement]. [Key feature 1] provides [user benefit]. [Key feature 2] enhances [capability].

[Second major area of improvement]. [Specific change] now allows users to [benefit]. [Another change] improves [aspect] by [improvement].

Additional improvements include [grouped minor features]. Several bug fixes improve robustness including [specific fixes that matter to users].

生成提交记录命令：

bash

undefined

For beta-to-beta:

测试版到测试版发布使用：

git log v4.0.0b2..HEAD --pretty=format:"%h %s" --no-merges

For stable (graduating from beta):

正式版（从测试版转正）发布使用：

git log v3.0.2..HEAD --pretty=format:"%h %s" --no-merges

undefined

git log v3.0.2..HEAD --pretty=format:"%h %s" --no-merges

undefined

Execute a Release

执行发布

When user asks to "execute release":

Run execute:
```
./release/release.sh --execute
```
Monitor CI: Watch GitHub Actions until successful deployment:
- Poll
```
gh run list
```
  for latest workflow run
- Wait for "completed" status with "success" conclusion
- If CI fails, report error and STOP (see Error Handling section)
Update Linear issue:
- Read
```
release/RELEASE_SUMMARY.md
```
  content
- Post release summary to Linear issue using
```
user-linear.create_comment
```
- Include PyPI link:
```
https://pypi.org/project/ai-todo/[version]/
```
- Include GitHub release link from workflow output
- Mark issue as "Done" using
```
user-linear.update_issue
```

当用户要求「执行发布」时：

运行执行命令：
```
./release/release.sh --execute
```
监控 CI 运行： 观察 GitHub Actions 直到部署成功：
- 轮询
```
gh run list
```
  获取最新工作流运行状态
- 等待状态变为「completed」且结论为「success」
- 如果 CI 运行失败，上报错误并停止流程（参考错误处理章节）
更新 Linear issue：
- 读取
```
release/RELEASE_SUMMARY.md
```
  内容
- 调用
```
user-linear.create_comment
```
  将发布摘要发布到 Linear issue
- 附上 PyPI 链接：
```
https://pypi.org/project/ai-todo/[version]/
```
- 附上工作流输出的 GitHub Release 链接
- 调用
```
user-linear.update_issue
```
  将 issue 标记为「已完成」

Abort a Release

中止发布

When user asks to "abort release":

Run abort:
```
./release/release.sh --abort [version]
```
Update Linear issue (if exists):
- Post abort summary to Linear issue using
```
user-linear.create_comment
```
- Include: reason for abort, version that was aborted, current state
- Mark issue as "Todo" using
```
user-linear.update_issue
```
  (reset for retry)

当用户要求「中止发布」时：

运行中止命令：
```
./release/release.sh --abort [version]
```
更新 Linear issue（如果存在）：
- 调用
```
user-linear.create_comment
```
  将中止摘要发布到 Linear issue
- 包含内容：中止原因、被中止的版本号、当前状态
- 调用
```
user-linear.update_issue
```
  将 issue 标记为「待办」（重置以便后续重试）

Error Handling

错误处理

If ANY error occurs:

STOP IMMEDIATELY.
Report the error.
If Linear issue exists: Post error details to issue
WAIT FOR USER. Do not attempt auto-recovery.

发生任意错误时：

立即停止流程
上报错误信息
如果存在关联的 Linear issue： 将错误详情发布到 issue 评论中
等待用户指示，不要尝试自动恢复

Forbidden Actions

禁止操作

❌ Never auto-execute after prepare.
❌ Never bypass CI/CD failures.
❌ NEVER use
--no-verify
on git commits.

❌ 严禁在准备发布完成后自动执行发布
❌ 严禁绕过 CI/CD 失败状态继续发布
❌ 严禁在 git commit 时使用
--no-verify
参数

Additional Resources

额外资源

Detailed Process: release/RELEASE_PROCESS.md
Version Strategy: Beta vs Stable release guidelines in RELEASE_PROCESS.md
Migration Handling: See RELEASE_PROCESS.md for adding migrations to releases
Release Scripts: All scripts are in
```
release/
```
directory

详细流程： release/RELEASE_PROCESS.md
版本策略： RELEASE_PROCESS.md 中包含测试版与正式版的发布规范
迁移处理： 如需在发布中添加迁移脚本请参考 RELEASE_PROCESS.md
发布脚本： 所有脚本均存放在
```
release/
```
目录下",