القائمة
Prepare a CRAN release of packages in the mlr3 ecosystem.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | mlr3ecosystem-release |
| description | Prepare a CRAN release of packages in the mlr3 ecosystem. |
| tools | Read, Edit, Glob, Grep, Bash, Write, AskUserQuestion, WebFetch |
Your role is to prepare a CRAN release of packages in the mlr3 ecosystem.
First, check that the prerequisites are available (in this order for efficiency):
DESCRIPTION. If
not, inform the user that this must be run from an R package root directory
and stop.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.gh repo view --json url.
If that fails, diagnose the error:
gh is not installed, try git remote -v to find a GitHub URL.gh is installed but not authenticated, suggest running gh auth login.Next, 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 (the
unreleased changes for the version being prepared). You will use this in the
next two steps: first to catch any undocumented changes (Step 3), then to
suggest an appropriate release type (Step 4).
The goal here is to catch anything that landed in the repo since the last
release but wasn't documented in NEWS.md. Omissions are easy to miss during
development, and this is the last chance to add them before CRAN submission.
This step must run before the version number is calculated: the release
type (and therefore the new version) is inferred from what NEWS.md contains,
so the NEWS must be complete first. For example, an undocumented breaking
change would otherwise lead to a patch or minor release when a major release is
warranted.
First, find the last release tag and list commits since then:
LAST_TAG=$(git tag --sort=-version:refname | head -1)
git log "${LAST_TAG}..HEAD" --oneline --no-merges
If there are no tags yet (first release), use the initial commit:
git log --oneline --no-merges
Then read the first section of NEWS.md (the unreleased changes for the
version being prepared). Compare the commit list against the NEWS entries: look
for commits that describe user-facing changes (new features, bug fixes,
behaviour changes, deprecations) that do not appear to have a corresponding
entry.
Ignore commits that are purely internal and don't affect users, such as:
If you find likely missing entries, summarise them clearly for the user and
ask whether they want to add them to NEWS.md before proceeding. If the user
says yes, open NEWS.md and add the missing entries under the first
(unreleased) section, then confirm with the user before moving on.
With NEWS.md now complete, read the first section again and use it to suggest
an appropriate release type:
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):
Calculate the new version by manipulating the current version according to the user's answer. For example:
1.2.3 + Major release → 2.0.01.2.3 + Minor release → 1.3.01.2.3 + Patch release → 1.2.40.2.1.9000 + Patch release → 0.2.20.2.1.9003 + Minor release → 0.3.0Note: 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}".
Before making any changes, check whether the package currently has any issues on CRAN. Fetch the CRAN checks page for the package:
https://cloud.r-project.org/web/checks/check_results_${PACKAGE_NAME}.html
Use the WebFetch tool with the prompt "Extract ALL check results from the table. For each row list the flavour and the status (OK, NOTE, WARNING, or ERROR). Also list any additional issues noted below the table." to retrieve and parse the page.
If the page is not found (404): The package is not yet on CRAN (first release). Skip this step silently and continue.
If any check flavour shows ERROR, WARNING, or NOTE: Display the issues clearly to the user, including the affected flavour(s) and their status, and inform them that existing CRAN check issues should be resolved before submitting a new release. Stop the workflow.
If all check flavours show OK: Inform the user that all CRAN checks are passing and continue with the release workflow.
Check whether a branch named release already exists (locally or on the
remote). If it does, ask the user using AskUserQuestion:
Question: "A 'release' branch already exists. How should we proceed?" Header: "Existing branch" Options:
If the user chooses to delete it, run:
git branch -D release
git push origin --delete release 2>/dev/null || true
Then create a new branch from main:
git checkout main
git pull origin main
git checkout -b release
If gh is available and authenticated, run the following R command to create a
GitHub release issue:
Rscript -e 'usethis::use_release_issue(version = "${NEW_VERSION}")'
After the command succeeds, retrieve the issue number that was just created:
gh issue list --limit 1 --json number --jq '.[0].number'
Store this as ${ISSUE_ID} for use in Step 12.
If gh is not available, skip this step and inform the user that they can
create the release issue manually later. In that case, ${ISSUE_ID} will be
unknown.
Run the following R command to update the version in DESCRIPTION and NEWS.md:
Rscript -e 'usethis::use_version(which = "major")'
Replace "major" with "minor" or "patch" depending on the release type
chosen in Step 4.
Run the following R command to check for invalid URLs:
Rscript -e 'urlchecker::url_check()'
If there are any invalid URLs, ask the user if they should be fixed.
Check for the presence of the Remotes field in the DESCRIPTION file.
If it is present, ask the user if it should be removed (CRAN does not allow
packages with a Remotes field).
The cran-comments.md file documents the test environments and any notes for
the CRAN team. CRAN reviewers read this file, so it's important to keep it
current for every submission.
Check whether cran-comments.md exists:
If it does not exist, create it with this template:
## Test environments
- local: R version x.y.z, Platform
## R CMD check results
0 errors | 0 warnings | 0 notes
## Reverse dependencies
Checked with revdepcheck::revdep_check(). No new problems.
Inform the user that cran-comments.md has been created and they should fill
in the actual test environments and R CMD check results before submitting to
CRAN.
If it does exist, read it and inform the user that they should update it for the new release (e.g., updated R version, new check results, response to any previous CRAN reviewer comments).
Commit the changes with the message release: ${NEW_VERSION}:
git add DESCRIPTION NEWS.md
git commit -m "release: ${NEW_VERSION}"
Push the branch and open a pull request:
git push -u origin release
gh pr create \
--title "release: ${NEW_VERSION}" \
--body "Closes #${ISSUE_ID}" \
--base main \
--head release
If ${ISSUE_ID} is unknown (because Step 7 was skipped), omit the --body
flag and add it manually after the PR is created.
Show the user the pull request URL on success.
If gh is not available, display the branch name and instruct the user to
open a pull request manually on GitHub.
Inform the user that they should now perform a reverse dependency check, fix any issues found, and submit the release to CRAN. Wait until the user confirms that the release has been accepted by CRAN before proceeding to the next step.
IMPORTANT: Always use --squash when merging. A squash merge is mandatory — never use a regular merge or rebase merge.
Merge the pull request and checkout the main branch:
gh pr merge --squash --delete-branch release
git checkout main
git pull origin main
Use this exact R command — do not substitute gh release create or any other
approach. usethis::use_github_release() reads NEWS.md to populate the
release notes and tags the commit correctly, which manual approaches would miss.
Rscript -e 'usethis::use_github_release()'
Use this exact R command — do not edit DESCRIPTION by hand or use a different
version string. usethis::use_dev_version() appends .9000 in the correct
R-package convention and adds the development section header to NEWS.md.
Rscript -e 'usethis::use_dev_version(push = FALSE)'
Commit and push the changes:
git add DESCRIPTION NEWS.md
git commit -m "release: ${NEW_VERSION}.9000"
git push origin main
The workflow is now complete. Inform the user that the release of ${PACKAGE_NAME} ${NEW_VERSION} is done.
Spellcheck an R package with cspell, fix genuine typos in source files, and add legitimate domain words to .cspell/project-words.txt. Use when the user asks to spellcheck the package, run cspell, fix typos, or clean up the project dictionary.
Creates or bootstraps R packages by applying the shared template files from `package/`, including editor, lint, build, and AI guidance config.` rules copied into a target package.
Comprehensive guidance for Quarto document authoring and R Markdown migration. Use this skill when: (1) Writing new Quarto documents (.qmd) with best practices, (2) Converting R Markdown (.Rmd) documents to Quarto, (3) Migrating bookdown, blogdown, xaringan, or distill projects to Quarto, (4) Understanding Quarto's code cell syntax with hashpipe (#|) options, (5) Setting up cross-references for figures, tables, sections, and equations, (6) Using Quarto-specific markdown features like callouts, divs, and spans, (7) Configuring YAML front matter for documents and projects, (8) Finding and using Quarto extensions.
Name all unnamed or incorrectly named R code chunks in a .qmd file using the pattern `[file-name]-[number]` (e.g. `intro-001`, `intro-002`). Use when the user wants to add or standardize chunk labels in a Quarto file.
Prepare R packages for CRAN submission by checking for common ad-hoc requirements not caught by devtools::check(). Use when: (1) Preparing a package for first CRAN release, (2) Preparing a package update for CRAN resubmission, (3) Reviewing a package to ensure CRAN compliance, (4) Responding to CRAN reviewer feedback. Covers documentation requirements, DESCRIPTION field standards, URL validation, examples, and administrative requirements.
Creates a pull request from current changes, monitors GitHub CI, and debugs any failures until CI passes. Use this when the user says "create pr", "make a pr", "open pull request", "submit pr", "pr for these changes", or wants to get their current work into a reviewable PR. Assumes the project uses git, is hosted on GitHub, and has GitHub Actions CI with automated checks (lint, build, tests, etc.). Does NOT merge - stops when CI passes and provides the PR link.