create-release-checklist

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create an R Package Release Checklist

创建R包发布检查清单

Generate a release checklist for an R package and create the corresponding GitHub issue.

为R包生成发布检查清单，并创建对应的GitHub issue。

Overview

概述

This skill guides you through creating a R package release checklist issue on GitHub by:

Determining the current version and prompting for release type.
Generating an initial checklist.
Prompting the user for additional customization.
Creating a GitHub issue from the final checklist.

本技能将通过以下流程引导你在GitHub上创建R包发布检查清单issue：

确定当前版本，询问用户发布类型。
生成初始检查清单。
询问用户是否需要额外自定义内容。
基于最终版清单创建GitHub issue。

Prerequisites

前置要求

The working directory must be an R package with a
```
DESCRIPTION
```
file at the root.
The
```
usethis
```
R package must be available.

And to enable automatic issue creation:

The
```
gh
```
CLI must be installed and authenticated.
The R package must be associated with a GitHub repository.

工作目录必须是R包根目录，且根目录下存在
```
DESCRIPTION
```
文件。
必须安装有
```
usethis
```
R包。

若要启用自动创建issue功能，还需满足：

已安装
```
gh
```
CLI并完成身份验证。
当前R包已关联GitHub仓库。

Workflow

工作流

Step 1: Validation

步骤1：验证

First, check that the prerequisites are available (in this order for efficiency):

Check that the working directory contains a file called
```
DESCRIPTION
```
. If not, inform the user that this must be run from an R package root directory and stop.
Use
```
Rscript -e 'utils::packageVersion("usethis")'
```
to check if the
```
usethis
```
package is installed. If not, instruct the user to install it with
```
install.packages("usethis")
```
, then stop.
Determine the GitHub URL for the repository, if one exists. First try
```
gh repo view --json url
```
. If that fails, diagnose the error:
- If
```
gh
```
  is not installed, try running
```
git remote -v
```
  to find a GitHub URL.
- If the local repo does not have a GitHub remote, suggest the user connect the package to GitHub using
```
usethis::use_github()
```
  . Offer to run this command for the user; if they decline, continue without a GitHub URL.
- If
```
gh
```
  is installed but not authenticated and the repo has a GitHub remote, suggest that the user run
```
gh auth login
```
  .

If any check fails, inform the user of the specific issue with clear instructions on how to fix it, then stop the workflow. Do not proceed to the next step until all prerequisites are met.

首先检查前置要求是否满足（按以下顺序执行以提升效率）：

检查工作目录下是否存在
```
DESCRIPTION
```
文件。如果不存在，告知用户必须在R包根目录下运行本工具，终止流程。
执行
```
Rscript -e 'utils::packageVersion("usethis")'
```
检查
```
usethis
```
包是否安装。如果未安装，指导用户执行
```
install.packages("usethis")
```
安装，终止流程。
确定仓库的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
```
  完成验证。

如果任意检查不通过，告知用户具体问题及清晰的修复方案，终止流程。所有前置要求满足前不要进入下一步。

Step 2: Initialization

步骤2：初始化

Next, you need to determine the current package's name and version. Read the

DESCRIPTION

file and extract the

Version:

and

Package:

fields from it.

Then, check if a

NEWS.md

file exists. If it does, read the first section (typically the most recent unreleased changes) to understand what kind of changes have been made. Use this to suggest an appropriate release type:

If the NEWS mentions "breaking changes", "breaking", "BREAKING", or similar language, suggest a Major release.
If the NEWS mentions only "bug fixes", "fixes", "patch", or similar language with no new features, suggest a Patch release.
Otherwise (new features, improvements, enhancements), suggest a Minor release.

Display the current version to the user and ask them what type of release this should be using the AskUserQuestion tool. Make the suggested release type the first option with "(Recommended)" appended to the label:

Question: "What type of release is this?" Header: "Release type" Options (with recommended option first):

Major (X.0.0) - Breaking changes (add "(Recommended)" if suggested)
Minor (x.X.0) - New features but without breaking changes (add "(Recommended)" if suggested)
Patch (x.x.X) - Bug fixes only (add "(Recommended)" if suggested)

Calculate the new version by manipulating the current version according to the user's answer. For example:

Current version
```
1.2.3
```
+ Major release →
```
2.0.0
```
Current version
```
1.2.3
```
+ Minor release →
```
1.3.0
```
Current version
```
1.2.3
```
+ Patch release →
```
1.2.4
```
Current version
```
0.2.1.9000
```
+ Patch release →
```
0.2.2
```
Current version
```
0.2.1.9003
```
+ Minor release →
```
0.3.0
```

Note: If the current version ends in

.9xxx

(R-style development versions), strip that suffix before calculating the new version.

Display: "Preparing release checklist for ${PACKAGE_NAME} ${CURRENT_VERSION} → ${NEW_VERSION}".

接下来需要确定当前包的名称和版本。读取

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) - 仅修复bug（如果是推荐选项则添加「(推荐)」）

根据用户选择的发布类型计算新版本号，示例如下：

当前版本
```
1.2.3
```
+ 主版本发布 →
```
2.0.0
```
当前版本
```
1.2.3
```
+ 次版本发布 →
```
1.3.0
```
当前版本
```
1.2.3
```
+ 补丁版本发布 →
```
1.2.4
```
当前版本
```
0.2.1.9000
```
+ 补丁版本发布 →
```
0.2.2
```
当前版本
```
0.2.1.9003
```
+ 次版本发布 →
```
0.3.0
```

注意：如果当前版本以

.9xxx

结尾（R风格的开发版本号），计算新版本号前先移除该后缀。

展示提示：「正在为 ${PACKAGE_NAME} 生成发布检查清单 ${CURRENT_VERSION} → ${NEW_VERSION}」。

Step 3: Checklist Generation

步骤3：生成检查清单

Generate an initial checklist using the

scripts/generate_checklist.R

script included with this skill:

bash

undefined

使用本技能自带的

scripts/generate_checklist.R

脚本生成初始检查清单：

bash

undefined

If the GitHub URL is known:

已知GitHub URL时执行：

Rscript "${SKILL_DIR}/scripts/generate_checklist.R" "${NEW_VERSION}" "${GITHUB_URL}"

Otherwise:

未知GitHub URL时执行：

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


(Where `${SKILL_DIR}` represents the directory where this skill is installed.)

Ignore any "Setting active project..." lines in the output.

Read the generated checklist (which is Markdown) and display it to the user.

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


（其中`${SKILL_DIR}`代表本技能的安装目录。）

忽略输出中所有「Setting active project...」开头的行。

读取生成的Markdown格式检查清单，展示给用户。

Step 4: User Customization

步骤4：用户自定义

Use the AskUserQuestion tool to ask:

Question: "Would you like to customize the checklist before creating the issue?" Header: "Customize?" Options:

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

If the user wants to customize the checklist, enter an iterative refinement loop:

Ask: "Suggest items that should be added or any items that can be safely removed, or confirm that there are no more changes requested."
Based on the user's feedback, update the checklist (add items, remove items, reword items, etc.). Keep the checklist in Markdown format with proper checkbox syntax (
```
- [ ]
```
for tasks).
Display the updated checklist to the user.
Ask: "Does this look good or do you have more suggestions?"
If the user has more suggestions, go back to step 2. If the user confirms it looks good, exit the loop and proceed to Step 5.

The checklist should be maintained as a Markdown string throughout this process so it can be easily passed to the GitHub issue creation command.

使用AskUserQuestion工具询问：

问题：「创建issue前是否需要自定义检查清单？」标题：「是否自定义？」选项：

否，直接按当前内容创建issue
是，我要自定义内容

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

询问：「请提出需要新增的项、可以移除的项，或确认没有更多修改需求。」
根据用户反馈更新检查清单（新增项、移除项、修改表述等），保持Markdown格式，使用正确的复选框语法（任务用
```
- [ ]
```
标识）。
向用户展示更新后的检查清单。
询问：「内容是否符合要求，还是需要更多修改？」
如果用户还有修改需求，回到步骤2。如果用户确认内容无误，退出循环进入步骤5。

整个过程中检查清单需保存为Markdown字符串，方便后续传入GitHub issue创建命令。

Step 5: GitHub Issue Creation

步骤5：创建GitHub Issue

The final checklist should be formatted as Markdown with proper sections and checkboxes.

If
gh
is available and authenticated, use it to create the GitHub issue yourself, passing the checklist content directly via stdin:

bash

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

Then show the user:

A success message with the issue URL.
The suggestion "You can now use the 'do-release-checklist' skill to walk through the checklist tasks." (Note: This is a companion skill that helps guide users through executing the checklist items. If this skill doesn't exist yet in your repository, you may omit this suggestion.)

If
gh
is not available, display the checklist to the user with instructions to manually create a GitHub issue:

Show the suggested issue title: "Release ${PACKAGE_NAME} ${NEW_VERSION}"
Show the full checklist content formatted as Markdown.
Instruct the user to copy the content and create the issue manually at their repository's issues page.

最终的检查清单需要是格式正确的Markdown内容，包含合理的分区和复选框。

如果
gh
可用且已完成身份验证，直接使用该工具创建GitHub issue，通过stdin传入清单内容：

bash

gh issue create \
  --title "Release ${PACKAGE_NAME} ${NEW_VERSION}" \
  --body-file - <<'EOF'
[此处填写检查清单内容]
EOF

然后向用户展示：

成功提示及issue的URL。
建议「你现在可以使用'do-release-checklist'技能引导你完成清单中的所有任务。」（注：这是配套技能，用于引导用户执行检查清单中的任务。如果你的仓库中还没有该技能，可以省略这条建议。）

如果
gh
不可用，向用户展示检查清单，指导用户手动创建GitHub issue：

展示建议的issue标题：「Release ${PACKAGE_NAME} ${NEW_VERSION}」
展示完整的Markdown格式检查清单内容。
指导用户复制内容，到自己仓库的issues页面手动创建issue。

Error Handling

错误处理

If the GitHub issue creation fails (when using

gh

), check for common issues:

Authentication errors: Ensure
```
gh auth status
```
shows the user is logged in. Suggest running
```
gh auth login
```
if needed.
Repository permissions: The user must have write access to create issues. Check with
```
gh repo view
```
to verify they have the correct permissions.
Network errors: If there are connectivity issues, suggest retrying the command or checking their internet connection.
Invalid Markdown: If the issue body has formatting errors, verify the checklist Markdown is properly formatted with valid syntax.

If the issue creation fails, preserve the checklist content and offer to:

Retry the command.
Display the checklist for manual issue creation instead.

如果使用

gh

创建GitHub issue失败，检查常见问题：

身份验证错误：执行
```
gh auth status
```
确认用户已登录，必要时建议用户执行
```
gh auth login
```
。
仓库权限问题：用户需要有写权限才能创建issue，执行
```
gh repo view
```
验证用户是否有对应权限。
网络错误：如果存在连接问题，建议重试命令或检查网络连接。
Markdown格式错误：如果issue正文存在格式错误，检查检查清单的Markdown语法是否正确。

如果issue创建失败，保留检查清单内容，向用户提供以下选项：

重试命令。
展示检查清单，改为手动创建issue。