Back to Details

version-bump-tag

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Version Bump & Tag Management — Development Guide

版本升级与标签管理 — 开发指南

You are an expert on semantic versioning and release management. Use this knowledge when bumping versions, creating tags, or troubleshooting release pipelines.
您是语义化版本控制和发布管理方面的专家。在进行版本升级、创建标签或排查发布流水线问题时，请运用这些知识。

What It Is

什么是版本升级与标签管理

A systematic approach to version management that keeps all project files in sync, creates proper git tags, and triggers CI/CD release pipelines.
This project's scripts:
  • ./app/scripts/bump-version.sh
    — Version bumping
  • ./app/scripts/redeploy.sh
    — Re-trigger failed releases
这是一种系统化的版本管理方法，可保持所有项目文件同步，创建规范的Git标签，并触发CI/CD发布流水线。
本项目的脚本:
  • ./app/scripts/bump-version.sh
    — 版本升级脚本
  • ./app/scripts/redeploy.sh
    — 重新触发失败的发布

Quick Reference (This Project)

快速参考（本项目）

bash
undefined
bash
undefined

Bump and release

升级版本并发布

./app/scripts/bump-version.sh patch # 0.1.0 → 0.1.1 ./app/scripts/bump-version.sh minor # 0.1.0 → 0.2.0 ./app/scripts/bump-version.sh major # 0.1.0 → 1.0.0 git push && git push --tags
./app/scripts/bump-version.sh patch # 0.1.0 → 0.1.1 ./app/scripts/bump-version.sh minor # 0.1.0 → 0.2.0 ./app/scripts/bump-version.sh major # 0.1.0 → 1.0.0 git push && git push --tags

Other options

其他选项

./app/scripts/bump-version.sh --set 2.0.0 # Explicit version ./app/scripts/bump-version.sh patch --dry-run # Preview changes ./app/scripts/bump-version.sh patch --no-git # Skip commit/tag
./app/scripts/bump-version.sh --set 2.0.0 # 设置指定版本 ./app/scripts/bump-version.sh patch --dry-run # 预览变更 ./app/scripts/bump-version.sh patch --no-git # 跳过提交/标签

Re-deploy failed release

重新部署失败的发布

./app/scripts/redeploy.sh # Current version ./app/scripts/redeploy.sh v0.1.5 # Specific version
undefined
./app/scripts/redeploy.sh # 当前版本 ./app/scripts/redeploy.sh v0.1.5 # 指定版本
undefined

Semantic Versioning

语义化版本控制

MAJOR.MINOR.PATCH
  │     │     └── Bug fixes (backward compatible)
  │     └──────── New features (backward compatible)
  └────────────── Breaking changes (incompatible API)
BumpWhenExample
patch
Bug fixes, minor tweaks1.0.0 → 1.0.1
minor
New features, no breaking changes1.0.0 → 1.1.0
major
Breaking changes, major rewrites1.0.0 → 2.0.0
MAJOR.MINOR.PATCH
  │     │     └── Bug修复（向后兼容）
  │     └──────── 新功能（向后兼容）
  └────────────── 破坏性变更（API不兼容）
升级类型适用场景示例
patch
Bug修复、小调整1.0.0 → 1.0.1
minor
新增功能、无破坏性变更1.0.0 → 1.1.0
major
破坏性变更、重大重构1.0.0 → 2.0.0

Pre-release Versions

预发布版本

1.0.0-alpha.1    # Early development
1.0.0-beta.1     # Feature complete, testing
1.0.0-rc.1       # Release candidate
1.0.0-alpha.1    # 早期开发阶段
1.0.0-beta.1     # 功能完成，测试阶段
1.0.0-rc.1       # 发布候选版本

Version Files by Project Type

不同项目类型的版本文件

Tauri Applications (This Project)

Tauri应用（本项目）

FileFormat
package.json
"version": "X.Y.Z"
src-tauri/tauri.conf.json
"version": "X.Y.Z"
src-tauri/Cargo.toml
version = "X.Y.Z"
src-tauri/Cargo.lock
Auto-updated
UI status barDisplay string
文件格式
package.json
"version": "X.Y.Z"
src-tauri/tauri.conf.json
"version": "X.Y.Z"
src-tauri/Cargo.toml
version = "X.Y.Z"
src-tauri/Cargo.lock
自动更新
UI状态栏显示字符串

Node.js Projects

Node.js项目

FileFormat
package.json
"version": "X.Y.Z"
package-lock.json
Auto-updated
文件格式
package.json
"version": "X.Y.Z"
package-lock.json
自动更新

Rust Projects

Rust项目

FileFormat
Cargo.toml
version = "X.Y.Z"
Cargo.lock
Auto-updated
文件格式
Cargo.toml
version = "X.Y.Z"
Cargo.lock
自动更新

Pre-Push Validation

推送前验证

Always validate before releasing:
bash
undefined
发布前务必验证：
bash
undefined

Quick check

快速检查

git status --porcelain | grep -q . && echo "UNCOMMITTED CHANGES" && exit 1 git fetch origin git log @{u}..HEAD --oneline | grep -q . && echo "UNPUSHED COMMITS" && exit 1 echo "Ready to release"
undefined
git status --porcelain | grep -q . && echo "存在未提交变更" && exit 1 git fetch origin git log @{u}..HEAD --oneline | grep -q . && echo "存在未推送提交" && exit 1 echo "准备就绪，可以发布"
undefined

Full Validation Function

完整验证函数

bash
validate_ready_to_release() {
    # Check for uncommitted changes
    if [[ -n "$(git status --porcelain)" ]]; then
        echo "ERROR: Uncommitted changes"
        git status --short
        return 1
    fi

    # Check for unpushed commits
    git fetch origin --quiet
    local AHEAD=$(git log @{u}..HEAD --oneline 2>/dev/null | wc -l | tr -d ' ')
    if [[ "$AHEAD" -gt 0 ]]; then
        echo "ERROR: $AHEAD unpushed commit(s)"
        return 1
    fi

    echo "Ready to release"
    return 0
}
bash
validate_ready_to_release() {
    # 检查未提交变更
    if [[ -n "$(git status --porcelain)" ]]; then
        echo "错误：存在未提交变更"
        git status --short
        return 1
    fi

    # 检查未推送提交
    git fetch origin --quiet
    local AHEAD=$(git log @{u}..HEAD --oneline 2>/dev/null | wc -l | tr -d ' ')
    if [[ "$AHEAD" -gt 0 ]]; then
        echo "错误：存在 $AHEAD 个未推送提交"
        return 1
    fi

    echo "准备就绪，可以发布"
    return 0
}

Git Tag Operations

Git标签操作

Creating Tags

创建标签

bash
undefined
bash
undefined

Annotated tag (recommended)

带注释的标签（推荐）

git tag -a v1.0.0 -m "Release v1.0.0"
git tag -a v1.0.0 -m "Release v1.0.0"

With release notes

附带发布说明

git tag -a v1.0.0 -m "Release v1.0.0
  • Feature: Added user auth
  • Fix: Memory leak resolved
  • Chore: Updated deps"
undefined
git tag -a v1.0.0 -m "Release v1.0.0
  • Feature: Added user auth
  • Fix: Memory leak resolved
  • Chore: Updated deps"
undefined

Pushing Tags

推送标签

bash
git push origin v1.0.0      # Single tag
git push --tags             # All tags
git push && git push --tags # Commits + tags
bash
git push origin v1.0.0      # 推送单个标签
git push --tags             # 推送所有标签
git push && git push --tags # 推送提交 + 标签

Listing Tags

列出标签

bash
git tag -l                  # All tags
git tag -l "v1.*"           # Pattern match
git show v1.0.0             # Tag details
git describe --tags --abbrev=0  # Latest tag
bash
git tag -l                  # 列出所有标签
git tag -l "v1.*"           # 按模式匹配列出
git show v1.0.0             # 查看标签详情
git describe --tags --abbrev=0  # 查看最新标签

Deleting Tags

删除标签

bash
git tag -d v1.0.0                    # Local
git push origin :refs/tags/v1.0.0    # Remote
bash
git tag -d v1.0.0                    # 删除本地标签
git push origin :refs/tags/v1.0.0    # 删除远程标签

Recreating Tags (Re-release)

重新创建标签（重新发布）

bash
git tag -d v1.0.0
git push origin :refs/tags/v1.0.0
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0
bash
git tag -d v1.0.0
git push origin :refs/tags/v1.0.0
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

Redeployment

重新部署

When a release fails mid-build, use redeployment to re-trigger without version change.
当发布在构建中途失败时，可通过重新部署来重新触发流程，无需更改版本。

What Redeploy Does

重新部署的作用

  1. Deletes tag locally (if exists)
  2. Deletes tag on remote (if exists)
  3. Recreates annotated tag at HEAD
  4. Pushes new tag
  5. CI/CD workflow re-triggers
  1. 删除本地标签（如果存在）
  2. 删除远程标签（如果存在）
  3. 在HEAD位置重新创建带注释的标签
  4. 推送新标签
  5. 重新触发CI/CD工作流

Manual Redeployment

手动重新部署

bash
VERSION="v0.1.5"
bash
VERSION="v0.1.5"

Validate first

先验证

git status --porcelain | grep -q . && echo "Uncommitted changes!" && exit 1
git status --porcelain | grep -q . && echo "存在未提交变更！" && exit 1

Delete and recreate

删除并重新创建

git tag -d "$VERSION" 2>/dev/null || true git push origin ":refs/tags/$VERSION" 2>/dev/null || true git tag -a "$VERSION" -m "Release $VERSION" git push origin "refs/tags/$VERSION"
undefined
git tag -d "$VERSION" 2>/dev/null || true git push origin ":refs/tags/$VERSION" 2>/dev/null || true git tag -a "$VERSION" -m "Release $VERSION" git push origin "refs/tags/$VERSION"
undefined

When to Redeploy

重新部署的场景

  • CI/CD workflow failed mid-build
  • Build artifacts corrupted
  • Code signing failed
  • Secrets/environment updated
  • Artifact upload failed
  • CI/CD工作流在构建中途失败
  • 构建产物损坏
  • 代码签名失败
  • 密钥/环境变量已更新
  • 产物上传失败

Complete Release Workflow

完整发布工作流

Manual Steps

手动步骤

bash
undefined
bash
undefined

1. Ensure clean state

1. 确保工作区干净

git status # No uncommitted changes
git status # 无未提交变更

2. Get current version

2. 获取当前版本

CURRENT=$(jq -r '.version' package.json)
CURRENT=$(jq -r '.version' package.json)

3. Calculate new version

3. 计算新版本

IFS='.' read -r major minor patch <<< "$CURRENT" NEW="${major}.${minor}.$((patch + 1))"
IFS='.' read -r major minor patch <<< "$CURRENT" NEW="${major}.${minor}.$((patch + 1))"

4. Update all version files

4. 更新所有版本文件

(Use bump script or edit manually)

—

5. Commit

—
git add -A git commit -m "chore: bump version to v${NEW}"
#（使用升级脚本或手动编辑）

6. Tag

5. 提交变更

git tag -a "v${NEW}" -m "Release v${NEW}"
git add -A git commit -m "chore: bump version to v${NEW}"

7. Push

6. 创建标签

git push && git push --tags
undefined
git tag -a "v${NEW}" -m "Release v${NEW}"

Using This Project's Script

7. 推送提交和标签

bash
./app/scripts/bump-version.sh patch
git push && git push --tags
The script handles steps 2-6 automatically.
git push && git push --tags
undefined

Version Comparison in Bash

使用本项目的脚本

bash
VERSION="1.2.3"
IFS='.' read -r MAJOR MINOR PATCH <<< "$VERSION"
bash
./app/scripts/bump-version.sh patch
git push && git push --tags
该脚本会自动处理步骤2-6。

Patch bump

Bash中的版本比较

PATCH=$((PATCH + 1)) NEW="${MAJOR}.${MINOR}.${PATCH}" # 1.2.4
bash
VERSION="1.2.3"
IFS='.' read -r MAJOR MINOR PATCH <<< "$VERSION"

Minor bump

升级补丁版本

MINOR=$((MINOR + 1)); PATCH=0 NEW="${MAJOR}.${MINOR}.${PATCH}" # 1.3.0
PATCH=$((PATCH + 1)) NEW="${MAJOR}.${MINOR}.${PATCH}" # 1.2.4

Major bump

升级次版本号

MAJOR=$((MAJOR + 1)); MINOR=0; PATCH=0 NEW="${MAJOR}.${MINOR}.${PATCH}" # 2.0.0
undefined
MINOR=$((MINOR + 1)); PATCH=0 NEW="${MAJOR}.${MINOR}.${PATCH}" # 1.3.0

Useful Commands

升级主版本号

ActionCommand
Current version
jq -r '.version' app/package.json
Latest tag
git describe --tags --abbrev=0
All tags
git tag -l
Remote tags
git ls-remote --tags origin
Tag exists?
git rev-parse v1.0.0 >/dev/null 2>&1 && echo "exists"
Commits since tag
git log v1.0.0..HEAD --oneline
MAJOR=$((MAJOR + 1)); MINOR=0; PATCH=0 NEW="${MAJOR}.${MINOR}.${PATCH}" # 2.0.0
undefined

Common Gotchas

实用命令

  1. Tag format must match workflow trigger — If workflow triggers on 
    v*
    , use 
    v0.1.0
    not 
    0.1.0
    .
  2. Push commits before tags — Tags reference commits; the commit must exist on remote first.
  3. Version files must all match — Mismatch causes build failures. Use the bump script.
  4. Cargo.lock needs regeneration — After editing Cargo.toml, run 
    cargo update -p <pkg>
    .
  5. Don't amend tagged commits — Creates divergent history. Create new commit + tag instead.
  6. Annotated tags for releases — Lightweight tags (
    git tag v1.0.0
    ) lack metadata. Use 
    -a
    .
  7. Tag deletion is not instant — GitHub may cache tags briefly. Wait a moment before recreating.
  8. CI runs against tagged commit — Ensure all changes are committed before tagging.
  9. Pre-release versions sort correctly — 
    1.0.0-alpha.1 < 1.0.0-beta.1 < 1.0.0-rc.1 < 1.0.0
  10. Conventional commits for bumps — Use 
    chore: bump version to vX.Y.Z
    or 
    release: vX.Y.Z
    .
操作命令
获取当前版本
jq -r '.version' app/package.json
获取最新标签
git describe --tags --abbrev=0
列出所有标签
git tag -l
列出远程标签
git ls-remote --tags origin
检查标签是否存在
git rev-parse v1.0.0 >/dev/null 2>&1 && echo "存在"
查看标签之后的提交
git log v1.0.0..HEAD --oneline
—

常见注意事项

—
  1. 标签格式必须匹配工作流触发器 — 如果工作流在
    v*
    标签时触发，请使用
    v0.1.0
    而非
    0.1.0
    。
  2. 先推送提交再推送标签 — 标签关联提交，提交必须先同步到远程仓库。
  3. 所有版本文件必须保持一致 — 版本不匹配会导致构建失败，请使用升级脚本。
  4. 需要重新生成Cargo.lock — 编辑Cargo.toml后，运行
    cargo update -p <pkg>
    。
  5. 不要修改已打标签的提交 — 会导致历史分叉，应创建新提交并打新标签。
  6. 发布使用带注释的标签 — 轻量标签（
    git tag v1.0.0
    ）缺少元数据，请使用
    -a
    参数。
  7. 标签删除不会立即生效 — GitHub可能会短暂缓存标签，重新创建前请稍作等待。
  8. CI会基于打标签的提交运行 — 打标签前请确保所有变更已提交。
  9. 预发布版本排序正确 — 
    1.0.0-alpha.1 < 1.0.0-beta.1 < 1.0.0-rc.1 < 1.0.0
  10. 版本升级使用约定式提交信息 — 使用
    chore: bump version to vX.Y.Z
    或
    release: vX.Y.Z
    。