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
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 releasecreate-github-release - general GitHub release creationsetup-github-actions-ci - triggers pkgdown rebuild on releasebuild-pkgdown-site - documentation site reflects new version