bump-and-release

bump-and-release Skill Description

This skill is intended to guide AI agents on how to correctly perform version bumping and release preparation for the ask-bridge project, as well as maintain the Traditional Chinese release notes after the GitHub Release is created.

🎯 Applicable Scenarios

When the user requests:

• 「Bump version / Bump patch version / Bump minor version」
• "Upgrade the version number / release a new version / prepare a Release"
• 「Bump and release」

Be sure to enable and follow the standard operating procedure described in this skill to ensure that the version information in the configuration and installation scripts on all platforms remains consistent.

---

📋 List of Files to Update

The version number must be updated synchronously in the following files:

File Path	Field or Variable Format	Description
Cargo.toml	version = "X.Y.Z"	Rust project definition file.
package.json	"version": "X.Y.Z",	NPM package definition file.
src/main.rs	#[command(version = "X.Y.Z")]	Built-in version display of the CLI command-line tool (Clap attribute).
install.ps1	$Version = "X.Y.Z"	Download version in the Windows PowerShell installation script.
install.sh	VERSION="X.Y.Z"	Download version in the Linux/macOS Shell installation script.
scripts/ask.sh	VERSION="X.Y.Z"	Version number of the project auxiliary script.

[!IMPORTANT] The version numbers of the above 6 files must be completely consistent. After updating,compilation verification must be performedto automatically update Cargo.lock。

---

🔄 Standard Operating Procedure (SOP)

Step 1: Analyze the Upgrade Type

1. Patch upgrade (X.Y.Z to X.Y.(Z+1)): Suitable for bug fixes and very minor feature adjustments.
2. Minor upgrade (X.Y.Z to X.(Y+1).0): Suitable for adding new features (backward compatible).
3. Major upgrade (X.Y.Z to (X+1).0.0): Suitable for updates with major breaking changes (Breaking Changes).

Step 2: Modify the Version Number

Use an appropriate code editing tool to replace the old version numbers in the above 6 files with the new version number.

Step 3: Perform Verification and Update the Lockfile

After modifying the configuration files, Rust program checks must be performed, which will automatically synchronously update Cargo.lock：

cargo check

(Optionally run cargo build --release to ensure the release version can be built normally)

To verify npm-related tests, run in the project directory:

npm test

Step 4: Git Commit and Push the Main Branch

Following the project's Git conventions, all version-number-related modifications should be merged into a single commit when committing, and the Conventional Commits 1.0.0 convention should be adopted, with the log providing a complete Traditional Chinese (zh-tw) description.

This step only allows pushing main, and Tags must not be created or pushed. Before pushing, first record the commit SHA to be released; subsequent CI queries, Tag creation, and consistency checks must all use this immutable SHA, and must not switch to the HEAD。

Execution example:

set -euo pipefail

# 1. 提交所有版本相關變更，且確認目前位於 main
[ "$(git branch --show-current)" = "main" ] || {
  echo "目前不在 main；禁止發布。" >&2
  exit 1
}

git add .

commit_msg_file="$(mktemp -t codex-commit-message)"
cat > "$commit_msg_file" <<'EOF'
chore(release): bump version to X.Y.Z

此提交將專案各平台之版本與設定檔同步提升至 X.Y.Z：

- 更新 Cargo.toml 與 package.json 套件版本號。
- 更新 src/main.rs 中 Clap 內建 CLI 版本資訊。
- 同步更新 install.ps1、install.sh 與 scripts/ask.sh 腳本中的發布版本變數。
- 自動同步更新 Cargo.lock。
EOF

git commit -F "$commit_msg_file"
release_commit="$(git rev-parse HEAD)"
git push origin main

Step 5: Wait for and Confirm Remote CI Success

After local verification passes, you must still wait for the GitHub Actions .github/workflows/ci.yml to complete for the same release commit. Only when all of the following conditions are met can you proceed to the Tag step:

1. The Workflow must be ci.yml, the event must be push。
2. headSha must equal the release_commit。
3. status must be completed，conclusion must be success。
4. After CI completes,origin/main must still point exactly to release_commit。

CI quality gate example:

repo="doggy8088/ask-bridge"

# 先確認 main push 已更新到待發布 commit
git fetch origin main --quiet
if [ "$(git rev-parse refs/remotes/origin/main)" != "$release_commit" ]; then
  echo "遠端 main 與待發布 commit 不一致；禁止建立或推送 Tag。" >&2
  exit 1
fi

# GitHub Actions 建立 run 可能有短暫延遲；最多等待 5 分鐘讓 run 出現
ci_run_id=""
for _ in $(seq 1 30); do
  ci_run_id="$(gh run list \
    --repo "$repo" \
    --workflow ci.yml \
    --event push \
    --commit "$release_commit" \
    --limit 1 \
    --json databaseId \
    --jq '.[0].databaseId // empty')"
  [ -n "$ci_run_id" ] && break
  sleep 10
done

if [ -z "$ci_run_id" ]; then
  echo "逾時仍找不到 commit $release_commit 的 main push CI；禁止建立或推送 Tag。" >&2
  exit 1
fi

# failure、cancelled、timed_out 或其他非 success 結果都必須停止
if ! gh run watch "$ci_run_id" --repo "$repo" --exit-status --interval 10; then
  gh run view "$ci_run_id" --repo "$repo"
  echo "CI run $ci_run_id 未成功；禁止建立或推送 Tag。" >&2
  exit 1
fi

# watch 結束後再次驗證不可變後置條件，避免誤用其他 run
ci_state="$(gh run view "$ci_run_id" \
  --repo "$repo" \
  --json headSha,event,status,conclusion \
  --jq '[.headSha,.event,.status,.conclusion] | @tsv')"
expected_ci_state="$(printf '%s\tpush\tcompleted\tsuccess' "$release_commit")"
if [ "$ci_state" != "$expected_ci_state" ]; then
  echo "CI 後置條件不符：$ci_state；禁止建立或推送 Tag。" >&2
  exit 1
fi

# 等待期間 main 可能已前進；正式發布只允許目前 main 的最新 commit
git fetch origin main --quiet
if [ "$(git rev-parse refs/remotes/origin/main)" != "$release_commit" ]; then
  echo "CI 完成後遠端 main 已變更；應以新的 main HEAD 重新執行發布流程。" >&2
  exit 1
fi

[!CAUTION] If no CI run is found, the wait times out,gh auth/GitHub API/network error, or any non- success result occurs, stop unconditionally. Do not replace this gate with local tests, PR CI, manual workflow runs, or successful results from an old commit. If fixing the issue produces a new commit, you must update release_commit, push again, and wait for the CI of the new commit.

Step 6: Create and push the Tag

Only after the CI quality gate succeeds may the corresponding Git Tagbe created (format: vX.Y.Z). The Tag must explicitly point to the release_committhat has passed CI; it must not rely on the current HEAD, and existing Tags must not be overwritten or force-pushed.

Execution example:

tag="vX.Y.Z"

# 本機或遠端已有同名 Tag 時停止，先釐清既有 release 狀態
if git show-ref --verify --quiet "refs/tags/$tag"; then
  echo "本機 Tag $tag 已存在；禁止覆寫。" >&2
  exit 1
fi

if git ls-remote --exit-code --tags origin "refs/tags/$tag" >/dev/null 2>&1; then
  echo "遠端 Tag $tag 已存在；禁止覆寫。" >&2
  exit 1
fi

# 建立帶有註解的 Tag，明確鎖定已通過 CI 的 commit
git tag -a "$tag" "$release_commit" -m "Release $tag"

# 推送 Tag 後會觸發 Release，Release 發布後再觸發 Publish npm
git push origin "refs/tags/$tag"

Step 7: Update the GitHub Release Traditional Chinese release notes

Immediately after the GitHub Release is created, the Traditional Chinese (zh-tw) release notes must be added. Do not keep only the GitHub auto-generated Full Changelog link.

Data collection

1. Use gh release view vX.Y.Z --repo doggy8088/ask-bridge --json tagName,body,url,publishedAt to confirm the release has been created.
2. Use git log --reverse --pretty=format:'%h%x09%ad%x09%s' --date=short <previous-tag>..vX.Y.Z to view the commits for this version. If this is the first release, the previous tag does not exist; instead use git log --reverse --pretty=format:'%h%x09%ad%x09%s' --date=short vX.Y.Z。
3. Use git diff --stat <previous-tag>..vX.Y.Z and the necessary git diff <previous-tag>..vX.Y.Z -- <path> to confirm the actual scope of impact. If this is the first release, instead use:
   • git diff --stat --root vX.Y.Z
   • git diff --root vX.Y.Z -- <path>
4. If CHANGELOG.md already has content for this version, use git show vX.Y.Z:CHANGELOG.md for cross-checking, but still verify against the commits and diff; do not merely rewrite the changelog.

Release notes format

The release notes must use Markdown and Traditional Chinese (zh-tw), with wording kept in Taiwanese usage. The following sections are recommended and should be trimmed according to the actual changes:

## 發行重點

用 1 到 2 句說明此版本最重要的使用者可見變更。

## 新增

- 條列新增功能。

## 修正

- 條列錯誤修正或相容性修正。

## 文件與網站

- 條列文件、網站、README 或中繼資料更新。

## 測試

- 條列新增或執行過的驗證。

## 注意事項

- 條列安裝、相容性或遷移注意事項。

## 相關連結

- 完整變更紀錄: https://github.com/doggy8088/ask-bridge/compare/<previous-tag>...vX.Y.Z

The full changelog link for the first release can use:

- 完整變更紀錄: https://github.com/doggy8088/ask-bridge/commits/vX.Y.Z

Write to GitHub Release

Write the release notes to a random temporary file, confirm it is UTF-8 plain text, then use gh release edit to update:

release_notes_file="$(mktemp -t codex-release-notes)"
cat > "$release_notes_file" <<'EOF'
## 發行重點

本版...

## 相關連結

- 完整變更紀錄: https://github.com/doggy8088/ask-bridge/compare/<previous-tag>...vX.Y.Z
EOF

gh release edit vX.Y.Z --repo doggy8088/ask-bridge --notes-file "$release_notes_file"
gh release view vX.Y.Z --repo doggy8088/ask-bridge --json tagName,body,url

[!IMPORTANT] The release notes must describe facts that have been verified by commit, diff,CHANGELOG.md , or release asset status. If there is not enough information, the uncertain scope must be stated clearly; speculation is prohibited.

---

💡 Tips and tricks

[!TIP] Before changing the version number, it is recommended to first check whether the old version number (e.g., 0.1.2) appears in other files:

• macOS / Linux：
  • rg -n "0\.1\.2" .
  • If there is no rg, instead use:grep -RIn "0.1.2" .
• Windows PowerShell：
  • rg -n "0\.1\.2" .
  • If there is no rg, instead use:Get-ChildItem -Recurse -File | Select-String -Pattern "0.1.2" -SimpleMatch

[!CAUTION] Never modify only Cargo.toml while ignoring the $Versionin the installation script; this will cause users downloading and installing via curl or iwr to fetch the wrong version.