release-package-version

name	release-package-version
description	Release a new version of an R package including version bumping, NEWS.md updates, git tagging, GitHub release creation, and post-release development version setup. Use when a package is ready for a new patch, minor, or major release, after CRAN acceptance to create the corresponding GitHub release, or when setting up the development version bump immediately after a release.
license	MIT
allowed-tools	Read Write Edit Bash Grep Glob
metadata	{"author":"Philipp Thoss","version":"1.0","domain":"r-packages","complexity":"intermediate","language":"R","tags":"r, versioning, release, git-tags, changelog"}

Release Package Version

Execute the full version release cycle for an R package.

When to Use

• Ready to release a new version (bug fix, feature, or breaking change)
• After CRAN acceptance, creating a corresponding GitHub release
• Setting up post-release development version

Inputs

• Required: Package with changes ready for release
• Required: Release type: patch (0.1.0 -> 0.1.1), minor (0.1.0 -> 0.2.0), or major (0.1.0 -> 1.0.0)
• Optional: Whether to submit to CRAN (default: no, use submit-to-cran skill separately)

Procedure

Step 1: Determine Version Bump

Follow semantic versioning:

Change Type	Version Bump	Example
Bug fixes only	Patch	0.1.0 -> 0.1.1
New features (backward compatible)	Minor	0.1.0 -> 0.2.0
Breaking changes	Major	0.1.0 -> 1.0.0

Expected: The correct bump type (patch, minor, or major) is determined based on the nature of changes since the last release.

On failure: If unsure, review git log since the last tag and classify each change. Any breaking API change requires a major bump.

Step 2: Update Version

usethis::use_version("minor")  # or "patch" or "major"

This updates the Version field in DESCRIPTION and adds a heading to NEWS.md.

Expected: DESCRIPTION version updated. NEWS.md has a new section header for the release version.

On failure: If usethis::use_version() is not available, manually update the Version field in DESCRIPTION and add a # packagename x.y.z heading to NEWS.md.

Step 3: Update NEWS.md

Fill in the release notes under the new version heading:

# packagename 0.2.0

## New Features
- Added `new_function()` for processing data (#42)
- Support for custom themes in `plot_results()` (#45)

## Bug Fixes
- Fixed crash when input contains all NAs (#38)
- Corrected off-by-one error in `window_calc()` (#41)

## Minor Improvements
- Improved error messages for invalid input types
- Updated documentation examples

Use issue/PR numbers for traceability.

Expected: NEWS.md contains a complete summary of user-facing changes organized by category, with issue/PR numbers for traceability.

On failure: If changes are hard to reconstruct, use git log --oneline v<previous>..HEAD to list all commits since the last release and categorize them.

Step 4: Final Checks

devtools::check()
devtools::spell_check()
urlchecker::url_check()

Expected: devtools::check() returns 0 errors, 0 warnings, and 0 notes. Spell check and URL check find no issues.

On failure: Fix all errors and warnings before releasing. Add false-positive words to inst/WORDLIST for the spell checker. Replace broken URLs.

Step 5: Commit Release

git add DESCRIPTION NEWS.md
git commit -m "Release packagename v0.2.0"

Expected: A single commit containing the version bump in DESCRIPTION and the updated NEWS.md.

On failure: If other uncommitted changes are present, stage only DESCRIPTION and NEWS.md. Release commits should contain only version-related changes.

Step 6: Tag the Release

git tag -a v0.2.0 -m "Release v0.2.0"
git push origin main --tags

Expected: Annotated tag v0.2.0 created and pushed to the remote. git tag -l shows the tag locally; git ls-remote --tags origin confirms it on the remote.

On failure: If push fails, check that you have write access. If the tag already exists, verify it points to the correct commit with git show v0.2.0.

Step 7: Create GitHub Release

gh release create v0.2.0 \
  --title "packagename v0.2.0" \
  --notes-file NEWS.md

Or use:

usethis::use_github_release()

Expected: GitHub release created with release notes visible on the repository's Releases page.

On failure: If gh release create fails, ensure the gh CLI is authenticated (gh auth status). If usethis::use_github_release() fails, create the release manually on GitHub.

Step 8: Set Development Version

After release, bump to development version:

usethis::use_dev_version()

This changes version to 0.2.0.9000 indicating development.

git add DESCRIPTION NEWS.md
git commit -m "Begin development for next version"
git push

Expected: DESCRIPTION version is now 0.2.0.9000 (development version). NEWS.md has a new heading for the development version. Changes are pushed to the remote.

On failure: If usethis::use_dev_version() is not available, manually change the version to x.y.z.9000 in DESCRIPTION and add a # packagename (development version) heading to NEWS.md.

Validation

• Version in DESCRIPTION matches intended release
• NEWS.md has complete, accurate release notes
• R CMD check passes
• Git tag matches version (e.g., v0.2.0)
• GitHub release exists with release notes
• Post-release development version set (x.y.z.9000)

Common Pitfalls

• Forgetting to push tags: git push alone doesn't push tags. Use --tags or git push origin v0.2.0
• NEWS.md format: Use markdown headers matching the pkgdown/CRAN expected format
• Tagging wrong commit: Always tag after the version-bump commit, not before
• CRAN version already exists: CRAN won't accept a version that's already been published. Always increment.
• Development version in release: Never submit a .9000 version to CRAN

Related Skills

• submit-to-cran - CRAN submission after version release
• create-github-release - general GitHub release creation
• setup-github-actions-ci - triggers pkgdown rebuild on release
• build-pkgdown-site - documentation site reflects new version