釋包之版

行 R 包之全版釋之循環。

用時

• 已備釋新版（修訛、增功、破變）乃用
• CRAN 受後立對應之 GitHub 釋乃用
• 釋後立設發之版乃用

入

• 必要：包附已備釋之變
• 必要：釋類：修（0.1.0 -> 0.1.1）、次（0.1.0 -> 0.2.0）、主（0.1.0 -> 1.0.0）
• 可選：是否投 CRAN（默：否，獨用 submit-to-cran 技）

法

第一步：定版升

循語意之版：

變類	版升	例
唯修訛	修	0.1.0 -> 0.1.1
新功（向後相容）	次	0.1.0 -> 0.2.0
破變	主	0.1.0 -> 1.0.0

得：依自前釋來變之性，定正升類（修、次、主）。

敗則：若不確，閱 git log 自前標而分各變。任何破 API 之變需主升。

第二步：更版

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

此更 DESCRIPTION 中 Version 之欄並加首於 NEWS.md。

得：DESCRIPTION 之版已更。NEWS.md 有釋版之新段首。

敗則：若 usethis::use_version() 不可得，手更 DESCRIPTION 之 Version 欄並加 # packagename x.y.z 首於 NEWS.md。

第三步：更 NEWS.md

於新版首下填釋之記：

# 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

用問題/PR 號以資追溯。

得：NEWS.md 含對用者所見之變之全摘，以類組之，附問題/PR 號以資追。

敗則：若變難復，用 git log --oneline v<previous>..HEAD 列自前釋之諸提交而分之。

第四步：終察

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

得：devtools::check() 返 0 誤、0 警、0 注。拼察與 URL 察無患。

敗則：釋前修諸誤與警。加假陽詞於 inst/WORDLIST 供拼察。代斷 URL。

第五步：提交釋

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

得：單提交含 DESCRIPTION 之版升與更之 NEWS.md。

敗則：若有他未提之變，獨入 DESCRIPTION 與 NEWS.md。釋之提交宜獨含版相關之變。

第六步：標其釋

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

得：注解之標 v0.2.0 已立並推至遠端。git tag -l 示其於本地；git ls-remote --tags origin 確之於遠。

敗則：若推敗，察是否有書之權。若標已存，以 git show v0.2.0 驗其指正提交。

第七步：立 GitHub 之釋

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

或用：

usethis::use_github_release()

得：GitHub 之釋已立，釋之記現於庫之 Releases 頁。

敗則：若 gh release create 敗，確 gh CLI 已認證（gh auth status）。若 usethis::use_github_release() 敗，於 GitHub 手立其釋。

第八步：設發之版

釋後升至發之版：

usethis::use_dev_version()

此化版為 0.2.0.9000 表發中。

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

得：DESCRIPTION 之版今為 0.2.0.9000（發版）。NEWS.md 有發版之新首。變已推至遠端。

敗則：若 usethis::use_dev_version() 不可得，手化版為 x.y.z.9000 於 DESCRIPTION 並加 # packagename (development version) 首於 NEWS.md。

驗

• DESCRIPTION 之版合所欲釋
• NEWS.md 有全且確之釋記
• R CMD check 過
• git 標合版（如 v0.2.0）
• GitHub 之釋存附釋之記
• 釋後發版已設（x.y.z.9000）

陷

• 忘推標：獨 git push 不推標。用 --tags 或 git push origin v0.2.0
• NEWS.md 之式：用 markdown 之首合 pkgdown/CRAN 望之式
• 標誤提交：必於版升提交後標，非前
• CRAN 版已存：CRAN 不受已示之版。必增之
• 釋中之發版：永勿投 .9000 版於 CRAN

參

• submit-to-cran — 版釋後投 CRAN
• create-github-release — 通用 GitHub 釋之立
• setup-github-actions-ci — 釋觸 pkgdown 之重建
• build-pkgdown-site — 文站映新版