Strict versioning and release …

# Go 项目语义化版本管理规范与 CI 方案

一、版本管理规范

1. Tag 命名规则

• main 分支只允许 vX.Y.Z 格式：即 v1.2.3，X/Y/Z 均为非负整数，无前导零
• Go 模块兼容：tag 对应模块路径，多模块仓库需带子目录前缀（如 subdir/v1.2.3）
• 禁止非法形式：1.2.3（缺 v）、v1.2（缺补丁位）、v1.2.3-beta（预发布版禁止打在 main，须在独立分支验证后再合入）

2. 发布流程

1. 功能开发走 feature 分支 → PR 合入 main

2. 发布时由维护者打 tag 并推送：git tag v1.4.0 && git push origin v1.4.0

3. 版本号递增原则：

• 不兼容 API 变更 → 升主版本号（注意 Go module 路径需带 /v2）
• 向后兼容的新功能 → 次版本号
• 仅 bug 修复 → 补丁号

4. 一旦发布，对应 tag 不可移动或删除（保护 tag）

二、CI 校验脚本（GitHub Actions）

1. 校验 main 分支 tag 格式

```yaml

# .github/workflows/tag-check.yml

name: Tag Format Check

on:

push:

tags: ['v*']

jobs:

check-tag:

runs-on: ubuntu-latest

steps:

• name: Validate tag format on main

run: |

TAG="${GITHUB_REF#refs/tags/}"

if [[ ! "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then

echo "::error::Tag '$TAG' 不符合 vX.Y.Z 格式"

exit 1

fi

```

2. 禁止移动/覆盖已发布的 v2.3.0 及以后 tag

```yaml

• name: Block moving published tags (>= v2.3.0)

run: |

TAG="${GITHUB_REF#refs/tags/}"

git fetch --tags --force

# 若远端已存在同名 tag，说明有人试图覆盖

if git ls-remote --tags origin "refs/tags/${TAG}" | grep -q "refs/tags/${TAG}^{}"; then

echo "::error::Tag ${TAG} 已存在于远端，禁止覆盖已发布版本"

exit 1

fi

# 额外硬性拦截：v2.3.0 及以后一律禁止重新打补丁（重打）

MAJOR=$(echo "$TAG" | cut -d. -f1 | tr -d v)

MINOR=$(echo "$TAG" | cut -d. -f2)

if [ "$MAJOR" -gt 2 ] || { [ "$MAJOR" -eq 2 ] && [ "$MINOR" -ge 3 ]; }; then

#