发布管理与版本工作流

# SemVer 版本号正则匹配 ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*) (?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*) (?:\\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))? (?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ # 示例 1.0.0 # 正式版 1.0.0-alpha.1 # 内部测试版 1.0.0-beta.2 # 公开测试版 1.0.0-rc.1 # 候选发布版 2.0.0+build.20240501 # 带构建元数据

#!/usr/bin/env bash # next-version.sh — 根据 Git 日志自动计算下一个版本号 set -euo pipefail get_current_version() { # 从 Git 标签获取当前版本号 git describe --tags --abbrev=0 2>/dev/null || echo "0.0.0" } parse_commits() { local prev_tag="$1" # 获取从上一个版本标签至今的所有提交 git log "${prev_tag}..HEAD" --pretty=format:"%s" } calculate_next_version() { local current="$1" local major minor patch IFS='.' read -r major minor patch <<< "$current" local has_breaking=false local has_feature=false local has_fix=false while IFS= read -r commit; do case "$commit" in *'!'*|*'BREAKING CHANGE'*) has_breaking=true ;; 'feat'*) has_feature=true ;; 'fix'*) has_fix=true ;; esac done <<< "$(parse_commits "$(get_current_version)")" if $has_breaking; then echo "$((major + 1)).0.0" elif $has_feature; then echo "${major}.$((minor + 1)).0" elif $has_fix; then echo "${major}.${minor}.$((patch + 1))" else echo "${major}.${minor}.${patch}" fi } if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then calculate_next_version "$(get_current_version)" fi

# Conventional Commits 提交信息格式 <type>[optional scope]: <description> [optional body] [optional footer(s)] # 常见类型与变更日志分类对应 feat: → Added (新功能) fix: → Fixed (Bug修复) docs: → Changed (文档更新) style: → Changed (代码风格) refactor: → Changed (代码重构) perf: → Changed (性能优化) test: → Changed (测试相关) build: → Changed (构建系统) ci: → Changed (CI配置) chore: → Changed (杂项) revert: → Changed (回滚) # 破坏性变更标记 feat!: 添加了不兼容的API变更 fix(api)!: 修复了但破坏了向后兼容性 BREAKING CHANGE: 这是破坏性变更的详细描述

#!/usr/bin/env python3 """changelog-gen.py — 自动生成 CHANGELOG.md""" import re import subprocess from datetime import datetime from collections import defaultdict COMMIT_PATTERN = re.compile( r'^(?P<type>\w+)(\((?P<scope>[^)]+)\))?' r'(?P<breaking>!)?\s*:\s*(?P<description>.+)', re.IGNORECASE ) SECTION_MAP = { 'feat': 'Added', 'fix': 'Fixed', 'docs': 'Changed', 'style': 'Changed', 'refactor': 'Changed', 'perf': 'Changed', 'test': 'Changed', 'build': 'Changed', 'ci': 'Changed', 'chore': 'Changed', 'revert': 'Reverted', } def get_tagged_versions(): """获取所有版本标签及其对应的提交哈希""" result = subprocess.run( ['git', 'tag', '--sort=-version:refname', '--format=%(refname:short)'], capture_output=True, text=True, check=True ) tags = [t.strip() for t in result.stdout.splitlines() if t.strip()] versions = [] for tag in tags: if re.match(r'^v?\d+\.\d+\.\d+', tag): hash_result = subprocess.run( ['git', 'rev-list', '-n', '1', tag], capture_output=True, text=True, check=True ) versions.append((tag, hash_result.stdout.strip())) return versions def get_commits_between(start_hash, end_hash='HEAD'): """获取两个提交之间的所有提交""" if start_hash: result = subprocess.run( ['git', 'log', f'{start_hash}..{end_hash}', '--pretty=format:%H||%s||%b', '--no-merges'], capture_output=True, text=True ) else: result = subprocess.run( ['git', 'log', end_hash, '--pretty=format:%H||%s||%b', '--no-merges'], capture_output=True, text=True ) if result.returncode != 0: return [] commits = [] for line in result.stdout.strip().splitlines(): if not line: continue parts = line.split('||', 2) if len(parts) >= 2: commits.append({ 'hash': parts[0][:7], 'subject': parts[1], 'body': parts[2] if len(parts) > 2 else '' }) return commits def parse_commit(commit): """解析单个提交到变更日志条目""" match = COMMIT_PATTERN.match(commit['subject']) if not match: return None type_ = match.group('type').lower() scope = match.group('scope') breaking = match.group('breaking') == '!' or 'BREAKING CHANGE' in commit['body'] description = match.group('description') entry = { 'type': 'BREAKING' if breaking else SECTION_MAP.get(type_, 'Changed'), 'description': description, 'scope': f'**{scope}**' if scope else None, 'hash': commit['hash'], } return entry def generate_changelog(): """生成完整的 CHANGELOG.md 内容""" versions = get_tagged_versions() changelog_sections = [] # Unreleased 部分 unreleased_commits = get_commits_between( versions[0][1] if versions else None ) if unreleased_commits: entries = defaultdict(list) for c in unreleased_commits: parsed = parse_commit(c) if parsed: entries[parsed['type']].append(parsed) if entries: changelog_sections.append(('Unreleased', dict(entries))) # 已发布版本 for i, (tag, hash_val) in enumerate(versions): next_hash = versions[i + 1][1] if i + 1 < len(versions) else None commits = get_commits_between(next_hash, hash_val) entries = defaultdict(list) for c in commits: parsed = parse_commit(c) if parsed: entries[parsed['type']].append(parsed) if entries: changelog_sections.append((tag, dict(entries))) # 输出 Markdown lines = ['# Changelog', '', '所有重要变更均记录在此文件中。', ''] lines.append('格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，') lines.append('版本号遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。') lines.append('') for version, section in changelog_sections: if version == 'Unreleased': lines.append(f'## [Unreleased]') else: date_result = subprocess.run( ['git', 'log', '-1', '--format=%as', hash_val], capture_output=True, text=True, check=True ) date_str = date_result.stdout.strip() lines.append(f'## [{version.lstrip("v")}] - {date_str}') lines.append('') for section_name, entries in section.items(): lines.append(f'### {section_name}') lines.append('') for entry in entries: scope_str = f'({entry["scope"]}) ' if entry['scope'] else '' lines.append( f'- {scope_str}{entry["description"]} ' f'([{entry["hash"]}](https://github.com/...)' ) lines.append('') return '\n'.join(lines) if __name__ == '__main__': print(generate_changelog())

# 检查是否有未发布变更的 CI 步骤 if grep -q "## \[Unreleased\]" CHANGELOG.md; then # 提取 Unreleased 下的非空行数 unreleased_count=$(awk '/## \[Unreleased\]/,/^## \[/{ if(/^- /) count++ } END{print count}' CHANGELOG.md) if [ "$unreleased_count" -gt 0 ]; then echo "检测到 $unreleased_count 条未发布变更，建议发起新版本发布。" else echo "无待发布变更。" fi fi

#!/bin/bash # rollback.sh — 自动化回滚流程 set -euo pipefail ROLLBACK_VERSION="${1:-}" CURRENT_VERSION="$(git describe --tags --abbrev=0)" if [ -z "$ROLLBACK_VERSION" ]; then echo "用法: ./rollback.sh <target-version>" echo "当前版本: $CURRENT_VERSION" exit 1 fi echo "⚠️ 准备从 $CURRENT_VERSION 回滚到 $ROLLBACK_VERSION" # 步骤1: 创建回滚分支 git checkout -b "hotfix/rollback-${CURRENT_VERSION}" "v${ROLLBACK_VERSION}" echo "✅ 已创建回滚分支 hotfix/rollback-${CURRENT_VERSION}" # 步骤2: 增加补丁版本号 PATCH_VERSION=$(echo "$ROLLBACK_VERSION" | awk -F. '{$NF+=1; print}') NEW_VERSION="${PATCH_VERSION%.*}.$(( ${PATCH_VERSION##*.} ))" echo "ℹ️ 新的修复版本号: v${NEW_VERSION}" # 步骤3: 应用 revert 变更 git revert --no-commit "v${CURRENT_VERSION}" git commit -m "fix: 回滚 v${CURRENT_VERSION} 到 v${ROLLBACK_VERSION} 由于 v${CURRENT_VERSION} 存在严重问题，回滚至 v${ROLLBACK_VERSION}。 这是回滚版本 v${NEW_VERSION}。" # 步骤4: 打标签(CI 会处理后续发布) git tag -s "v${NEW_VERSION}" -m "Hotfix rollback v${NEW_VERSION}" echo "✅ 已创建版本 v${NEW_VERSION}，请通过 CI 触发发布。" # 步骤5: 推送到远程 git push origin "v${NEW_VERSION}" git push origin "hotfix/rollback-${CURRENT_VERSION}"

# npm version 命令 — 自动更新 package.json 并创建 Git tag npm version patch # 1.0.0 → 1.0.1 (补丁) npm version minor # 1.0.1 → 1.1.0 (次要) npm version major # 1.1.0 → 2.0.0 (主要) npm version premajor --preid alpha # 1.0.0 → 2.0.0-alpha.0 npm version prerelease --preid beta # 2.0.0-beta.0 → 2.0.0-beta.1 # 自定义版本号 npm version 3.5.2-rc.1 # 不创建 Git tag（与其他工具配合时） npm version patch --no-git-tag-version

#!/bin/bash # publish-npm.sh — 自动化 npm 包发布流程 set -euo pipefail echo "📦 npm 包发布流程启动" echo "========================" # 步骤1: 发布前检查 echo "" echo "🔍 步骤1: 运行发布前检查..." # 检查 package.json if [ ! -f "package.json" ]; then echo "❌ 错误: 未找到 package.json" exit 1 fi # 检查版本号是否合法 VERSION=$(node -p "require('./package.json').version") if ! echo "$VERSION" | grep -qP '^\d+\.\d+\.\d+'; then echo "❌ 错误: 版本号格式不正确: $VERSION" exit 1 fi # 检查 npm 登录状态 npm whoami &>/dev/null || { echo "❌ 错误: 未登录 npm，请先执行 npm login" exit 1 } # 检查是否有未提交的文件 if [ -n "$(git status --porcelain)" ]; then echo "❌ 错误: 存在未提交的变更，请先提交或暂存" exit 1 fi # 步骤2: 运行测试 echo "" echo "🧪 步骤2: 运行测试套件..." npm test || { echo "❌ 测试失败，终止发布" exit 1 } # 步骤3: 构建 echo "" echo "🔨 步骤3: 构建生产版本..." npm run build || { echo "❌ 构建失败，终止发布" exit 1 } # 步骤4: 检查发布文件 echo "" echo "📋 步骤4: 检查即将发布的文件..." npx npm-packlist | head -20 echo "... (共 $(npx npm-packlist | wc -l) 个文件)" echo "" # 步骤5: dry-run 测试 echo "🧪 步骤5: 执行发布 dry-run..." npm publish --dry-run || { echo "❌ Dry-run 失败，请检查配置" exit 1 } # 步骤6: 确认发布 echo "" echo "⚠️ 即将发布版本: $VERSION" read -p "是否继续发布? (y/N): " confirm if [ "$confirm" != "y" ] && [ "$confirm" != "Y" ]; then echo "已取消发布" exit 0 fi # 步骤7: 正式发布 echo "" echo "🚀 步骤7: 发布到 npm registry..." # 处理 OTP（双因素认证） if npm publish --otp 2>&1 | grep -q "one-time pass"; then echo "ℹ️ 需要 OTP 认证" read -p "请输入 6 位 OTP 验证码: " otp npm publish --otp="$otp" else npm publish fi # 步骤8: 发布验证 echo "" echo "✅ 步骤8: 验证发布结果..." sleep 3 npm view . version 2>/dev/null || { echo "⚠️ 无法立即验证，请手动检查: npm view $(node -p "require('./package.json').name")" } echo "" echo "🎉 npm 包发布完成! v$VERSION"

# 设置发布标签 npm publish --tag beta # 推送时标记为 beta npm publish --tag next # 标记为下一个候选版本 npm publish --tag legacy # 旧版维护分支 # 管理已有标签 npm dist-tag ls # 列出所有标签 npm dist-tag add @scope/pkg@1.0.0 latest # 设置标签 npm dist-tag rm @scope/pkg@1.0.0 beta # 移除标签 # 推荐的标签策略 # latest → 最新稳定版 (默认) # next → 即将发布的候选版 (rc) # beta → 公开测试版 # alpha → 内部测试版 # legacy → 旧版 LTS 维护 # 预发布版本自动标记 npm version prerelease --preid beta # 如果版本号为 1.2.3-beta.0，publish 时自动 # 使用 --tag beta 而不是 --tag latest

# pyproject.toml — 现代 Python 包配置 [build-system] requires = ["setuptools>=64", "wheel"] build-backend = "setuptools.build_meta" [project] name = "my-package" version = "1.2.3" description = "一个示例 Python 包" readme = "README.md" requires-python = ">=3.9" license = { text = "MIT" } authors = [ { name = "开发者", email = "dev@example.com" }, ] keywords = ["example", "cli", "automation"] classifiers = [ "Development Status :: 5 - Production/Stable", "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Topic :: Software Development :: Libraries", ] dependencies = [ "click>=8.0", "requests>=2.28", ] [project.urls] Homepage = "https://github.com/user/my-package" Documentation = "https://my-package.readthedocs.io" Repository = "https://github.com/user/my-package" "Bug Tracker" = "https://github.com/user/my-package/issues" [project.scripts] my-cli = "my_package.cli:main" [tool.setuptools.packages.find] include = ["my_package*"]

#!/bin/bash # publish-pypi.sh — 自动化 PyPI 包发布流程 set -euo pipefail echo "🐍 PyPI 包发布流程启动" echo "========================" PYPI_REGISTRY="${1:-pypi}" # 参数: pypi 或 testpypi # 步骤1: 清理旧构建 echo "" echo "🧹 步骤1: 清理旧的构建产物..." rm -rf dist/ build/ *.egg-info echo "✅ 清理完成" # 步骤2: 确认版本号 echo "" echo "📋 步骤2: 确认包版本..." if [ -f "pyproject.toml" ]; then VERSION=$(grep -E '^version\s*=' pyproject.toml | head -1 | sed 's/.*"\(.*\)".*/\1/') elif [ -f "setup.cfg" ]; then VERSION=$(grep -E '^version\s*=' setup.cfg | sed 's/.*=\s*//') elif [ -f "setup.py" ]; then VERSION=$(python3 setup.py --version 2>/dev/null) else echo "❌ 错误: 未找到 pyproject.toml, setup.cfg 或 setup.py" exit 1 fi echo "ℹ️ 当前版本号: $VERSION" # 步骤3: 安装构建依赖 echo "" echo "🔧 步骤3: 确保构建工具已安装..." python3 -m pip install --quiet --upgrade build twine echo "✅ build 和 twine 已就绪" # 步骤4: 构建分发包 echo "" echo "🔨 步骤4: 构建分发包 (sdist + wheel)..." python3 -m build echo "✅ 构建完成" echo " 生成的文件:" ls -lh dist/ # 步骤5: 检查分发包 echo "" echo "🔍 步骤5: 检查分发包内容..." twine check dist/* || { echo "⚠️ Twine 检查发现警告，但不阻止发布" } # 步骤6: 选择 registry echo "" echo "🌐 步骤6: 选择发布目标..." if [ "$PYPI_REGISTRY" = "testpypi" ]; then echo " 目标: TestPyPI (https://test.pypi.org/legacy/)" REGISTRY_URL="--repository-url https://test.pypi.org/legacy/" else echo " 目标: PyPI (https://upload.pypi.org/legacy/)" REGISTRY_URL="" fi # 步骤7: 发布前确认 echo "" echo "⚠️ 即将发布 v$VERSION 到 $PYPI_REGISTRY" read -p "是否继续? (y/N): " confirm if [ "$confirm" != "y" ] && [ "$confirm" != "Y" ]; then echo "已取消发布" exit 0 fi # 步骤8: 上传到 PyPI echo "" echo "🚀 步骤8: 上传分发包..." if [ -n "${PYPI_TOKEN:-}" ]; then echo " 使用环境变量 PYPI_TOKEN 进行认证" twine upload $REGISTRY_URL dist/* \ --username __token__ --password "$PYPI_TOKEN" else twine upload $REGISTRY_URL dist/* fi # 步骤9: 验证发布 echo "" echo "✅ 步骤9: 验证发布结果..." sleep 5 if [ "$PYPI_REGISTRY" = "testpypi" ]; then echo " 测试安装: pip install --index-url https://test.pypi.org/simple/ my-package==$VERSION" else if pip install "my-package==$VERSION" --quiet 2>/dev/null; then echo " ✅ 确认包 $VERSION 可正常安装" else echo " ⚠️ 无法立即验证，请手动检查" fi fi echo "" echo "🎉 PyPI 包发布完成! v$VERSION 已发布到 $PYPI_REGISTRY"

# TestPyPI 发布与安装测试 # 1. 发布到 TestPyPI ./publish-pypi.sh testpypi # 2. 从 TestPyPI 安装测试 pip install \ --index-url https://test.pypi.org/simple/ \ --extra-index-url https://pypi.org/simple/ \ my-package # 3. 验证功能 python3 -c " import my_package print(f'版本: {my_package.__version__}') print('导入成功!') " # 4. 卸载测试版本 pip uninstall my-package -y # 5. TestPyPI 与正式 PyPI 的配置区分 # ~/.pypirc 配置文件 [distutils] index-servers = pypi testpypi [pypi] username = __token__ password = pypi-xxxxx [testpypi] repository = https://test.pypi.org/legacy/ username = __token__ password = pypi-yyyyy

# Docker 镜像标签策略示例 # 完整的版本标签（最推荐用于生产） myapp:2.3.1 # 精确版本，不可变 myapp:2.3.1-alpine # 精确版本 + 基础镜像类型 myapp:2.3.1-slim # 主/次版本标签（可被新补丁覆盖） myapp:2 # 指向最新的 v2.x.x myapp:2.3 # 指向最新的 v2.3.x # 特殊用途标签 myapp:latest # 指向最新稳定版 myapp:next # 指向最新的预发布版 myapp:sha-abc123def # 基于 Git commit SHA（不可变引用） # 时间戳标签（用于回滚定位） myapp:20240501 # 基于构建日期 myapp:2.3.1-build.20240501.123456 # 推荐的生产环境标签组合 myapp:2.3.1 # 用于精确版本控制 myapp:sha-abc123def # 用于不可变部署引用

#!/bin/bash # build-multiarch.sh — 多架构 Docker 镜像构建与发布 set -euo pipefail IMAGE_NAME="${1:-myapp}" IMAGE_VERSION="${2:-latest}" # 支持的架构平台 PLATFORMS="linux/amd64,linux/arm64,linux/arm/v7" echo "🐳 Docker 多架构镜像构建与发布" echo "================================" echo "镜像名: $IMAGE_NAME" echo "版本: $IMAGE_VERSION" echo "架构: $PLATFORMS" # 步骤1: 创建并使用 buildx builder（如需） echo "" echo "🔧 步骤1: 初始化 buildx builder..." if ! docker buildx inspect multiarch-builder &>/dev/null; then docker buildx create --name multiarch-builder --driver docker-container --use echo "✅ 已创建 multiarch-builder" else docker buildx use multiarch-builder echo "✅ multiarch-builder 已就绪" fi # 步骤2: 登录容器仓库 echo "" echo "🔑 步骤2: 登录容器仓库..." if [ -n "${DOCKER_USERNAME:-}" ] && [ -n "${DOCKER_PASSWORD:-}" ]; then echo "$DOCKER_PASSWORD" | docker login -u "$DOCKER_USERNAME" --password-stdin echo "✅ 已登录" else echo "⚠️ 未设置 DOCKER_USERNAME/PASSWORD，使用本地认证状态" fi # 步骤3: 构建并推送多架构镜像 echo "" echo "🔨 步骤3: 构建并推送多架构镜像..." # 定义标签列表 TAGS=( "${IMAGE_NAME}:${IMAGE_VERSION}" "${IMAGE_NAME}:sha-${GITHUB_SHA:-local}" ) # 如果是语义化版本，额外添加主版本和次版本标签 if [[ "$IMAGE_VERSION" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+) ]]; then MAJOR="${BASH_REMATCH[1]}" MINOR="${BASH_REMATCH[1]}.${BASH_REMATCH[2]}" TAGS+=("${IMAGE_NAME}:${MAJOR}" "${IMAGE_NAME}:${MINOR}") fi # 如果是正式版（非预发布），更新 latest 标签 if [[ "$IMAGE_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then TAGS+=("${IMAGE_NAME}:latest") fi # 构建标签参数 TAG_ARGS=() for tag in "${TAGS[@]}"; do TAG_ARGS+=("-t" "$tag") done # 执行多架构构建 docker buildx build \ --platform "$PLATFORMS" \ ${TAG_ARGS[@]} \ --push \ --cache-from "type=registry,ref=${IMAGE_NAME}:cache" \ --cache-to "type=registry,ref=${IMAGE_NAME}:cache,mode=max" \ --build-arg BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ') \ --build-arg VERSION="${IMAGE_VERSION}" \ --build-arg REVISION="${GITHUB_SHA:-unknown}" \ -f Dockerfile \ . # 步骤4: 验证 manifest echo "" echo "✅ 步骤4: 验证 manifest 列表..." docker buildx imagetools inspect "${IMAGE_NAME}:${IMAGE_VERSION}" echo "" echo "🎉 Docker 镜像发布完成!" for tag in "${TAGS[@]}"; do echo " 📦 $tag" done

#!/bin/bash # scan-image.sh — Docker 镜像安全扫描 set -euo pipefail IMAGE="${1:-}" if [ -z "$IMAGE" ]; then echo "用法: ./scan-image.sh <image:tag>" exit 1 fi echo "🔒 开始安全扫描: $IMAGE" # 安装 Trivy（如未安装） if ! command -v trivy &>/dev/null; then echo "安装 Trivy..." # Linux # curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh # macOS # brew install trivy echo "⚠️ 请先安装 Trivy: https://trivy.dev" exit 1 fi # 设置严重级别阈值 # CRITICAL: 严重漏洞数不得超过此值 CRITICAL_THRESHOLD=0 HIGH_THRESHOLD=5 trivy image \ --severity CRITICAL,HIGH \ --no-progress \ --format table \ --exit-code 1 \ --ignore-unfixed \ "$IMAGE" || SCAN_EXIT=$? if [ ${SCAN_EXIT:-0} -ne 0 ]; then # 解析漏洞数量 CRITICAL_COUNT=$(trivy image --severity CRITICAL --no-progress --format json "$IMAGE" 2>/dev/null \ | python3 -c "import sys,json; data=json.load(sys.stdin); print(len(data.get('Results',[])[0].get('Vulnerabilities',[])))" 2>/dev/null || echo "?") echo "" echo "⚠️ 安全扫描发现问题!" echo " CRITICAL: $CRITICAL_COUNT (阈值: $CRITICAL_THRESHOLD)" if [ "$CRITICAL_COUNT" -gt "$CRITICAL_THRESHOLD" ]; then echo "❌ 严重漏洞数超过阈值，发布被阻止!" exit 1 fi echo "⚠️ 存在 HIGH 级别漏洞，建议修复后再发布" fi echo "✅ 安全扫描通过，镜像可发布"

#!/bin/bash # create-release.sh — 自动化创建 GitHub Release set -euo pipefail VERSION="${1:-}" if [ -z "$VERSION" ]; then echo "用法: ./create-release.sh <version>" echo "示例: ./create-release.sh v1.2.3" exit 1 fi # 确保标签存在 if ! git tag | grep -q "^${VERSION}$"; then echo "❌ 标签 ${VERSION} 不存在，请先创建标签" exit 1 fi echo "🚀 创建 GitHub Release: $VERSION" # 步骤1: 生成 Release Notes echo "" echo "📝 步骤1: 生成 Release Notes..." RELEASE_NOTES_FILE="/tmp/release-notes-${VERSION}.md" # 使用 gh 自动生成 Release Notes gh release view "$VERSION" --json body --jq '.body' 2>/dev/null \ || echo "无已存在的 Release Notes" # 自动生成（基于 Git 日志） cat > "$RELEASE_NOTES_FILE" << RELNOTESEOF ## ${VERSION} ### 变更摘要 $(git log --oneline --no-decorate "$(git tag --sort=-version:refname | head -1)..${VERSION}" \ | sed 's/^/- /') ### 安装说明 \`\`\`bash # npm npm install my-package@${VERSION#v} # pip pip install my-package==${VERSION#v} # Docker docker pull myapp:${VERSION#v} \`\`\` ### 更新提示 请查看 CHANGELOG.md 获取完整变更记录。 RELNOTESEOF echo "✅ Release Notes 已生成" # 步骤2: 收集附件 echo "" echo "📦 步骤2: 收集发布附件..." ASSETS=() # 检查常见的构建产物 for pattern in \ "dist/*.whl" "dist/*.tar.gz" \ "*.vsix" \ "build/*.exe" "build/*.dmg" "build/*.AppImage" \ "_build/**/*.msi" \ "target/release/*.tar.gz"; do for file in $pattern; do if [ -f "$file" ]; then ASSETS+=("$file") fi done done if [ ${#ASSETS[@]} -gt 0 ]; then echo " 找到 ${#ASSETS[@]} 个附件:" for asset in "${ASSETS[@]}"; do echo " - $asset ($(du -h "$asset" | cut -f1))" done else echo " ℹ️ 未找到附件文件" fi # 步骤3: 创建 Release echo "" echo "🎯 步骤3: 创建 GitHub Release..." gh release create "$VERSION" \ --title "$VERSION" \ --notes-file "$RELEASE_NOTES_FILE" \ ${ASSETS:+${ASSETS[@]}} \ --verify-tag \ --discussion-category "announcements" \ --latest # 步骤4: 验证 Release echo "" echo "✅ 步骤4: 验证 Release..." gh release view "$VERSION" --json name,url,tagName,createdAt RELEASE_URL=$(gh release view "$VERSION" --json url --jq '.url') echo "" echo "🎉 GitHub Release 创建成功!" echo " 地址: $RELEASE_URL"

# .github/workflows/release.yml — 全自动发布管道 name: Automated Release on: push: branches: [main] workflow_dispatch: inputs: version_bump: description: '版本升级类型' required: true default: 'patch' type: choice options: - patch - minor - major permissions: contents: write packages: write discussions: write env: DOCKER_IMAGE: ghcr.io/${{ github.repository }} jobs: release: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 with: fetch-depth: 0 fetch-tags: true - name: 设置 Node.js uses: actions/setup-node@v4 with: node-version: '20' registry-url: 'https://registry.npmjs.org' - name: 设置 Python uses: actions/setup-python@v5 with: python-version: '3.12' - name: 计算版本号 id: version run: | if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then BUMP="${{ github.event.inputs.version_bump }}" else BUMP="patch" fi npm version $BUMP --no-git-tag-version VERSION="v$(node -p "require('./package.json').version")" echo "version=$VERSION" >> $GITHUB_OUTPUT echo "将发布版本: $VERSION $BUMP" - name: 验证测试 run: | npm ci npm test - name: 构建 npm 包 run: npm run build - name: 发布到 npm run: | npm publish env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} - name: 构建并推送 Docker 镜像 uses: docker/build-push-action@v5 with: push: true tags: | ${{ env.DOCKER_IMAGE }}:${{ steps.version.outputs.version }} ${{ env.DOCKER_IMAGE }}:latest - name: 创建 Git 标签 run: | git config user.name "Release Bot" git config user.email "bot@example.com" git tag -a "${{ steps.version.outputs.version }}" \ -m "Release ${{ steps.version.outputs.version }}" git push origin "${{ steps.version.outputs.version }}" - name: 创建 GitHub Release env: GH_TOKEN: ${{ github.token }} run: | # 生成 Release Notes gh release create "${{ steps.version.outputs.version }}" \ --title "${{ steps.version.outputs.version }}" \ --generate-notes \ --verify-tag \ --latest

# CLAUDE.md — 发布管理技能定义 ## 技能: release **触发词**: /release, /publish, /deploy **描述**: 执行完整的版本发布流程，支持 patch/minor/major 升级类型 **执行流程**: 1. 确认当前分支是 main (如果是 Git Flow 则确认是 release/*) 2. 运行 `git status` 确保工作区干净 3. 读取 package.json 或 pyproject.toml 确认当前版本号 4. 询问用户升级类型 (patch/minor/major) 如未提供 5. 运行指定类型的 semver 升级 6. 更新 CHANGELOG.md (基于 Conventional Commits 自动生成) 7. 提交变更并创建版本标签 8. 根据项目类型执行发布: - package.json 存在 → npm publish - pyproject.toml 存在 → twine upload - Dockerfile 存在 → docker buildx build --push 9. 创建 GitHub Release 10. 验证发布结果 11. 回滚到 develop 分支 (Git Flow) **示例**: ``` /release patch # 补丁版本发布 /release minor # 次要版本发布 /release major # 主要版本发布 /release 2.0.0-rc.1 # 指定版本号发布 ``` **安全限制**: - 发布前必须确认用户意图 (双重确认) - 需要 GitHub Token、npm Token、PyPI Token 等环境变量 - 发布到 main 分支前必须通过所有测试

#!/bin/bash # preflight-check.sh — 发布前全面检查清单 set -euo pipefail PASS=0 FAIL=0 WARN=0 check() { local name="$1" local cmd="$2" local type="${3:-required}" echo -n "[ ] $name ... " if eval "$cmd" &>/dev/null; then echo "✅ 通过" ((PASS++)) else if [ "$type" = "required" ]; then echo "❌ 失败" ((FAIL++)) else echo "⚠️ 警告" ((WARN++)) fi fi } echo "========================================" echo " 发布前检查清单" echo "========================================" echo "" # 版本控制检查 check "Git 工作区干净" "git diff --stat --exit-code" check "Git 暂存区干净" "git diff --cached --stat --exit-code" check "当前在 main 分支" '[ "$(git branch --show-current)" = "main" ]' check "已推送到远程" "git push --dry-run 2>&1 | grep -q 'Everything up-to-date'" # 代码质量检查 check "单元测试全部通过" "npm test -- --run" "recommended" check "Lint 检查通过" "npm run lint -- --max-warnings=0" "recommended" check "类型检查通过" "npm run typecheck" "recommended" # 安全检查 check "依赖漏洞扫描" "npm audit --audit-level=high" "recommended" check "无硬编码密钥" '! grep -r --include="*.{js,ts,py,json,yaml}" -E "(sk-[a-zA-Z0-9]{20,}|AKIA[0-9A-Z]{16})" .' "recommended" # 构建检查 check "生产构建成功" "npm run build" check "构建产物大小正常" '[ $(du -sm dist/ | cut -f1) -lt 50 ]' # 文档检查 check "CHANGELOG.md 已更新" 'grep -q "Unreleased" CHANGELOG.md || grep -q "^## \[$(node -p "require(\"./package.json\").version")\]" CHANGELOG.md' check "README.md 版本号正确" 'grep -q "$(node -p "require(\"./package.json\").version")" README.md' "recommended" # Docker 检查 if [ -f "Dockerfile" ]; then check "Dockerfile 存在" "test -f Dockerfile" check "Docker 构建验证" "docker build -t check-build ." "recommended" fi echo "" echo "========================================" echo " 检查结果汇总" echo "========================================" echo " 通过: $PASS" echo " 失败: $FAIL" echo " 警告: $WARN" echo "========================================" if [ "$FAIL" -gt 0 ]; then echo "❌ $FAIL 项必要检查未通过，请修复后再发布" exit 1 fi echo "✅ 全部必要检查通过!"

# 发布管理核心原则速查表 # 1. 版本号 = API 契约 # MAJOR = 破坏性变更 # MINOR = 向后兼容的新功能 # PATCH = 向后兼容的 Bug 修复 # 2. 发布流程不可逆 # 版本号一旦发布，永不可覆盖 # 回滚 = 发布新的 PATCH 版本 # 3. 自动化一切 # 版本计算 → 变更日志 → 构建 → 测试 → 发布 # 人工只负责审批 # 4. 分步晋升 # Dev → Staging → TestPyPI → Production # 每一步都有独立验证 # 5. 安全优先 # GPG 签名标签 # 镜像漏洞扫描 # 环境变量管理密钥 # 最小权限原则