issue-lifecycle

Issue 生命周期处理技能

本 skill 将 FluxMarkdown 项目处理 GitHub Issue 的完整经验固化为可复用流程。 目标：不遗漏任何 issue，不遗漏任何贡献者，保持所有渠道信息一致。

---

核心原则（不可违反）

1. 语言对齐：回复语言必须与 issue 语言一致。英文 issue → 英文回复，中文 issue → 中文回复。
2. 不关闭 issue：只加 done label + 发评论。由 issue 作者决定是否关闭。
3. 信息一致性：CHANGELOG、GitHub Release Note、appcast.xml 三处描述必须一致，且都要体现 issue 号和贡献者感谢。
4. 不遗漏：每次发布后，系统性检查所有 open issue，不能只处理"明显相关"的。

---

阶段一：调查 —— 梳理当前 issue 状态

发布后或用户要求处理 issue 时，先做全局扫描。

# 1. 列出所有 open issue（含已标记 done 的）
gh issue list --state open --limit 50

# 2. 列出最近关闭的 issue（确认有无遗漏）
gh issue list --state closed --limit 20

# 3. 查看最近发布的版本
gh release list --limit 5

关键判断：对每个 issue，确认：

• 是否已在某个版本中修复/实现？（查 git log、CHANGELOG）
• 是否已回复？（查 issue comments）
• 是否已加 done label？

⚠️ 常见陷阱：CHANGELOG 更新后补充了条目，但 appcast.xml 的 <description> 是在更新前生成的，导致自动更新提示内容不全。每次修改 CHANGELOG 后必须检查 appcast.xml。

---

阶段二：定位 —— 确认修复归属

对每个疑似已修复的 issue，用 git log 精确确认：

# 查找包含 issue 关键词的 commit
git log --oneline --grep="#21" 
git log --oneline --grep="Mouseless"

# 查看 commit 详情，确认修复内容和所属版本
git show <commit-hash> --stat

# 确认该 commit 属于哪个 release tag
git tag --contains <commit-hash>

不要凭印象判断——必须以 git 记录为准。

---

阶段三：核查发布内容完整性

发布后（或发现信息不一致时），系统核查三个渠道：

3.1 检查 CHANGELOG.md

每个版本的 CHANGELOG 条目应包含：

• ✅ 功能描述清晰
• ✅ 关联 issue 号 (#N)
• ✅ 贡献者感谢 (thanks @username) —— 对于用户报告的 issue
• ✅ 所有该版本的 git commit 都有对应条目（用 git log v旧..v新 核对）

补全格式（中文条目）：

- **功能描述**: 修复/新增内容简述 (#issue号, thanks @username)
  - 技术细节 1
  - 技术细节 2

补全格式（英文条目，用于英文 issue 相关修复）：

- **Feature**: Fix/add description (#N, thanks @username)
  - Technical detail 1

3.2 检查 GitHub Release Note

gh release view v版本号 --json body -q '.body'

Release Note 内容应与 CHANGELOG 对应版本一致。如需更新：

gh release edit v版本号 --notes "$(cat <<'EOF'
### Added / Fixed / Changed
- **xxx**: ...

---
**Install / Update:**
```bash
brew update && brew upgrade --cask flux-markdown

Or download the DMG directly from the Assets below. EOF )"

### 3.3 检查 appcast.xml

appcast.xml 的 `<description>` 是 Sparkle 自动更新窗口中用户看到的内容，极易与 CHANGELOG 脱节。

```bash
# 查看当前最新版本的 description
python3 -c "
import re
with open('appcast.xml') as f:
    content = f.read()
m = re.search(r'(Version 最新版本.*?<description><!\[CDATA\[)(.*?)(\]\]></description>)', content, re.DOTALL)
if m:
    print(m.group(2).strip()[:500])
"

如不完整，直接编辑 appcast.xml 中对应 <description><![CDATA[...]]></description> 部分， 将 Markdown 转为 HTML 格式（<h3>/<ul><li>/<strong>/<code>），然后提交推送：

git add appcast.xml
git commit -m "docs(appcast): fix missing entries in v版本号 description"
git push origin master

---

阶段四：回复 issue

4.1 确定每个 issue 的处理状态

4.2 执行回复（中文 issue）

gh issue comment <NUMBER> --body "已在 [vX.Y.Z](https://github.com/xykong/flux-markdown/releases/tag/vX.Y.Z) 中修复。

**修复内容：**
- [与此 issue 相关的具体修复描述]

**更新方式：**
\`\`\`bash
brew update && brew upgrade --cask flux-markdown
\`\`\`
或从 [Releases 页面](https://github.com/xykong/flux-markdown/releases/tag/vX.Y.Z) 直接下载 DMG。

感谢你的反馈，这个问题的修复正是因为你的报告才得以推进！如有其他问题欢迎继续反馈 🙏"

4.3 执行回复（英文 issue）

gh issue comment <NUMBER> --body "Fixed in [vX.Y.Z](https://github.com/xykong/flux-markdown/releases/tag/vX.Y.Z)! 🎉

**What changed:**
- [Specific fix relevant to this issue]

**To update:**
\`\`\`bash
brew update && brew upgrade --cask flux-markdown
\`\`\`
Or download the DMG from the [Releases page](https://github.com/xykong/flux-markdown/releases/tag/vX.Y.Z).

Thanks for the report — your issue helped prioritize this fix! Please give it a try and let us know if everything looks good. 🙏"

4.4 加 done label

gh issue edit <NUMBER> --add-label "done"

注意：仅对已修复/已实现的 issue 加 done。尚未解决的 issue 不加。

---

阶段五：发布完整性自查清单

每次处理 issue 后，过一遍此清单：

[ ] git log 中每个 fix/feat commit 都有对应的 CHANGELOG 条目
[ ] 每个 CHANGELOG 条目都标注了 issue 号（如有）
[ ] 每个用户报告的修复都有 thanks @username
[ ] GitHub Release Note 内容与 CHANGELOG 一致
[ ] appcast.xml <description> 与 CHANGELOG 一致
[ ] 所有相关 open issue 都已回复
[ ] 已修复的 issue 都已加 done label
[ ] 未修复但已知的 issue 已回复说明状态
[ ] Feature Request 实现后已回复并感谢贡献者

---

常见遗漏模式（经验教训）

本 skill 从实际操作中总结出以下高频遗漏，每次处理前主动检查：

1. appcast.xml 与 CHANGELOG 脱节

场景：发布时先跑 generate-appcast.sh，之后才补充 CHANGELOG 条目，导致 appcast description 不完整。 检测：对比 appcast 最新 item 的 description 与 CHANGELOG 对应版本的内容。 修复：直接编辑 appcast.xml 的 CDATA 部分并推送。

2. 同一版本包含多个 commit，只记录了部分

场景：一次发布包含 5 个 commit（icon 修复、scroll 修复、RTL 新功能、window 修复、release bump），但 CHANGELOG 只写了最后一个。 检测：git log v上一版本..v当前版本 --oneline 列出所有 commit，逐一核对 CHANGELOG。 修复：补全所有遗漏条目。

3. Feature Request issue 没有回复

场景：bug fix 类 issue 都回复了，但 feature request 类（无 done label）被忽略。 检测：gh issue list 中过滤无 done label 的 issue，逐一确认是否已实现。 修复：实现后补发回复 + 加 done label。

4. 错误判断"未修复"而回复了误导信息

场景：没有仔细查 git log，凭印象以为未修复，给用户回复了"正在调查"。 预防：回复前必须执行 git log --oneline --grep="#issue号" 确认。

5. 回复语言错误

场景：用中文回复了英文 issue，或用英文回复了中文 issue。 预防：回复前看 issue 正文语言，严格对齐。

---

工具命令速查

# 查看所有 open issue（含 labels）
gh issue list --state open --limit 50

# 查看某 issue 的全部评论
gh api repos/xykong/flux-markdown/issues/<NUMBER>/comments --jq '.[].body'

# 查看某 issue 详情（作者、语言、内容）
gh issue view <NUMBER>

# 查找某 issue 相关 commit
git log --oneline --grep="#<NUMBER>"

# 确认 commit 属于哪个 tag
git tag --contains <commit-hash>

# 查看两个版本之间的所有 commit
git log v旧版本..v新版本 --oneline

# 加 done label
gh issue edit <NUMBER> --add-label "done"

# 发评论
gh issue comment <NUMBER> --body "..."

# 查看 release note
gh release view v版本号 --json body -q '.body'

# 更新 release note
gh release edit v版本号 --notes "..."

---

与发布流程的协作

本 skill 聚焦 issue 生命周期。完整的发布流程（版本号升级、DMG 构建、Homebrew 更新） 由 /publish 命令处理。两者协作关系：

/publish 发布新版本
    ↓
issue-lifecycle skill 处理 issue 回复
    ↓
检查 CHANGELOG / Release Note / appcast.xml 一致性
    ↓
回复所有相关 issue + 标记 done