create-release-checklist

创建 R 包发布检查清单

为 R 包生成发布检查清单，并创建相应的 GitHub 议题。

概述

此技能将引导你在 GitHub 上创建 R 包发布检查清单议题，具体包括：

• 确定当前版本并询问发布类型。
• 生成初始检查清单。
• 提示用户进行其他自定义。
• 根据最终检查清单创建 GitHub 议题。

先决条件

• 工作目录必须是 R 包的根目录，且其中包含 DESCRIPTION 文件。
• 必须安装 R 包 usethis。

要启用自动创建议题，还需满足以下条件：

• 必须安装并完成身份验证的 gh CLI。
• R 包必须关联到 GitHub 仓库。

工作流

第 1 步：验证

首先，检查先决条件是否满足（按以下顺序检查以提高效率）：

1. 检查工作目录中是否包含名为 DESCRIPTION 的文件。如果没有，告知用户必须在 R 包根目录中运行，然后停止。
2. 使用 Rscript -e 'utils::packageVersion("usethis")' 检查是否已安装 usethis 包。如果没有，指示用户使用 install.packages("usethis") 安装，然后停止。
3. 确定仓库的 GitHub URL（如果存在）。首先尝试运行 gh repo view --json url。如果失败，诊断错误：
   • 如果未安装 gh，尝试运行 git remote -v 查找 GitHub URL。
   • 如果本地仓库没有 GitHub 远程地址，建议用户使用 usethis::use_github() 将包连接到 GitHub。主动提出为用户运行此命令；如果用户拒绝，则在没有 GitHub URL 的情况下继续。
   • 如果已安装 gh，但尚未完成身份验证，并且仓库有 GitHub 远程地址，则建议用户运行 gh auth login。

如果任何检查失败，向用户说明具体问题，并清楚地告知如何解决，然后停止工作流。所有先决条件均满足之前，不要继续下一步。

第 2 步：初始化

接下来，确定当前包的名称和版本。读取 DESCRIPTION 文件，并从中提取 Version: 和 Package: 字段。

然后，检查是否存在 NEWS.md 文件。如果存在，阅读第一节（通常是最新的未发布更改），以了解所做更改的类型。根据这些信息建议合适的发布类型：

• 如果 NEWS 提到“breaking changes”、“breaking”、“BREAKING”或类似表述，建议进行 Major 发布。
• 如果 NEWS 仅提到“bug fixes”、“fixes”、“patch”或类似表述，且没有新功能，则建议进行 Patch 发布。
• 其他情况（新功能、改进、增强）建议进行 Minor 发布。

向用户显示当前版本，并使用 AskUserQuestion 工具询问发布类型。将建议的发布类型列为第一个选项，并在标签末尾附加“（推荐）”：

问题：“这是什么类型的发布？” 标题：“发布类型” 选项（推荐选项置于首位）：

• Major（X.0.0）- 破坏性更改（如果是建议选项，则附加“（推荐）”）
• Minor（x.X.0）- 新功能，但没有破坏性更改（如果是建议选项，则附加“（推荐）”）
• Patch（x.x.X）- 仅包含错误修复（如果是建议选项，则附加“（推荐）”）

根据用户的选择调整当前版本，计算新版本。例如：

• 当前版本 1.2.3 + Major 发布 → 2.0.0
• 当前版本 1.2.3 + Minor 发布 → 1.3.0
• 当前版本 1.2.3 + Patch 发布 → 1.2.4
• 当前版本 0.2.1.9000 + Patch 发布 → 0.2.2
• 当前版本 0.2.1.9003 + Minor 发布 → 0.3.0

注意：如果当前版本以 .9xxx 结尾（R 风格的开发版本），请在计算新版本前去掉该后缀。

显示：“正在为 ${PACKAGE_NAME} ${CURRENT_VERSION} → ${NEW_VERSION} 准备发布检查清单”。

步骤 3：生成检查清单

使用此技能附带的 scripts/generate_checklist.R 脚本生成初始检查清单：

# If the GitHub URL is known:
Rscript "${SKILL_DIR}/scripts/generate_checklist.R" "${NEW_VERSION}" "${GITHUB_URL}"

# Otherwise:
Rscript "${SKILL_DIR}/scripts/generate_checklist.R" "${NEW_VERSION}"

（${SKILL_DIR} 表示此技能的安装目录。）

忽略输出中的任何“Setting active project...”行。

阅读生成的检查清单（它是 Markdown 格式），并向用户展示。

步骤 4：自定义清单

使用 AskUserQuestion 工具询问：

问题：“Would you like to customize the checklist before creating the issue?” 标题：“Customize?” 选项：

• No, create the issue as-is
• Yes, let me customize it

如果用户想自定义检查清单，请进入迭代优化循环：

1. 询问：“Suggest items that should be added or any items that can be safely removed, or confirm that there are no more changes requested.”
2. 根据用户的反馈更新检查清单（添加项目、删除项目、改写项目等）。请使用包含正确复选框语法（- [ ] 表示任务）的 Markdown 格式。
3. 向用户展示更新后的检查清单。
4. 询问：“Does this look good or do you have more suggestions?”
5. 如果用户有更多建议，请返回步骤 2。如果用户确认没有问题，则退出循环并继续步骤 5。

整个过程中都应将检查清单保存为 Markdown 字符串，以便轻松传递给 GitHub issue 创建命令。

步骤 5：创建 GitHub Issue

最终检查清单应采用包含正确分节和复选框的 Markdown 格式。

如果 gh 可用且已完成身份验证，请使用它自行创建 GitHub issue，并通过标准输入直接传入检查清单内容：

gh issue create \
  --title "Release ${PACKAGE_NAME} ${NEW_VERSION}" \
  --body-file - <<'EOF'
[checklist content here]
EOF

然后向用户展示：

• 成功消息和 issue URL。
• 建议：“You can now use the 'do-release-checklist' skill to walk through the checklist tasks.”（注意：这是一个配套技能，可帮助用户逐项完成检查清单中的任务。如果仓库中尚不存在此技能，可以省略此建议。）

如果 gh 不可用，请向用户展示检查清单，并说明如何手动创建 GitHub issue：

• 显示建议的 issue 标题：“Release ${PACKAGE_NAME} ${NEW_VERSION}”
• 显示完整的 Markdown 格式检查清单。
• 告知用户复制内容，并前往仓库的 issues 页面手动创建 issue。

错误处理

如果创建 GitHub issue 失败（使用 gh 时），请检查常见问题：

• 身份验证错误：确保 gh auth status 显示用户已登录。如有需要，建议运行 gh auth login。
• 仓库权限：用户必须拥有写入权限才能创建 issue。使用 gh repo view 检查用户是否拥有相应权限。
• 网络错误：如果存在连接问题，建议重试命令或检查网络连接。
• 无效的 Markdown：如果 issue 正文存在格式错误，请确认检查清单的 Markdown 格式正确、语法有效。

如果创建 issue 失败，请保留检查清单内容，并提出以下选项：

• 重试命令。
• 改为显示检查清单，以便手动创建 issue。