發布套件版本

執行 R 套件之完整版本發布週期。

適用時機

• 已備發布新版本（修錯、功能或破壞性變更）
• CRAN 接受之後，建立對應之 GitHub 發布
• 設置發布後之開發版本

輸入

• 必要：含已備發布變更之套件
• 必要：發布類型：patch（0.1.0 -> 0.1.1）、minor（0.1.0 -> 0.2.0）或 major（0.1.0 -> 1.0.0）
• 選擇性：是否提交 CRAN（預設：否，宜獨用 submit-to-cran 技能）

步驟

步驟一：定版本變更

依語意化版本：

預期： 依上次發布以來變更之性質，確定正確之變更類型（patch、minor 或 major）。

失敗時： 若不確，檢視上次標籤以來之 git log 並對每變更分類。任何破壞性 API 變更皆須 major 變更。

步驟二：更新版本

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() 不可用，手動將版本改為 DESCRIPTION 中之 x.y.z.9000 並加 # 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 格式：用合 pkgdown／CRAN 預期格式之 markdown 標題
• 標錯提交：務於版本變更提交之後標籤，勿之前
• CRAN 版本已存在：CRAN 不接受已發布之版本。務遞增
• 開發版本入發布：永勿提交 .9000 版本至 CRAN

相關技能

• submit-to-cran — 版本發布後 CRAN 之提交
• create-github-release — 通用 GitHub 發布建立
• setup-github-actions-ci — 發布時觸發 pkgdown 重建
• build-pkgdown-site — 文件站反映新版本