Files
CodexandClaude Opus 4.7 e35e8a85bd 建立版本管理体系:CHANGELOG + bump 脚本 + pyproject 元数据 + 一致性测试
新增:
- CHANGELOG.md:Keep a Changelog 1.1.0 格式,回填 V3.0.0–V3.3.3 历史
- tools/dev/bump_version.py:一键 bump major/minor/patch,
  同步 version.py / pyproject.toml / CHANGELOG.md,并创建 git tag。
  支持 --dry-run / --no-tag。
- tests/test_version_consistency.py:9 个用例确保
  version.py、pyproject.toml、CHANGELOG.md 三处版本号一致

修改:
- pyproject.toml 加 [project] 元数据,version=3.3.3(PEP 440 形式,
  与 douyin/core/version.py 同步;后者带 V 前缀,是单一事实来源)

后续会给 V3.0.0 → V3.3.3 补打 git tag。

回归:353 个 pytest 用例通过;bump_version dry-run 三种模式(patch/minor/major/set)
全部输出正确。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-21 15:17:56 +08:00

286 lines
10 KiB
Python
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""bump_version.py — 单一入口的版本号 bump 工具。
版本号"单一事实来源"是 douyin/core/version.py 的 APP_VERSION(带 V 前缀,SemVer)。
本脚本同步以下 4 个位置:
1. douyin/core/version.py: APP_VERSION 与 APP_BUILD_DATE
2. pyproject.toml: [project] version(PEP 440 不支持 V 前缀,所以去掉前缀)
3. CHANGELOG.md: 把 [Unreleased] 段重命名为新版本,并新建空 [Unreleased]
4. git tag: vX.Y.Z(小写 v + 纯数字,符合大多数工具习惯)
用法:
python tools/dev/bump_version.py patch # V3.3.3 → V3.3.4
python tools/dev/bump_version.py minor # V3.3.3 → V3.4.0
python tools/dev/bump_version.py major # V3.3.3 → V4.0.0
python tools/dev/bump_version.py set V3.5.0 # 指定版本
可选参数:
--no-tag 不创建 git tag(仅更新文件,由人手工 tag)
--dry-run 只打印会改什么,不实际写
示例完整流程:
python tools/dev/bump_version.py patch
git diff # 看自动改了什么
# 编辑 CHANGELOG.md 把 Unreleased 那段挪进去(脚本已自动重命名空段)
git commit -am "chore(release): bump version to V3.3.4"
git push --follow-tags
"""
from __future__ import annotations
import argparse
import datetime as _dt
import re
import subprocess
import sys
from pathlib import Path
from typing import Optional, Tuple
PROJECT_ROOT = Path(__file__).resolve().parents[2]
VERSION_PY = PROJECT_ROOT / "douyin" / "core" / "version.py"
PYPROJECT_TOML = PROJECT_ROOT / "pyproject.toml"
CHANGELOG_MD = PROJECT_ROOT / "CHANGELOG.md"
# ============================================================
# 当前版本:从 version.py 读取
# ============================================================
VERSION_RE = re.compile(r'^APP_VERSION\s*=\s*"(V?\d+\.\d+\.\d+)"', re.MULTILINE)
BUILD_DATE_RE = re.compile(r'^APP_BUILD_DATE\s*=\s*"(\d{4}-\d{2}-\d{2})"', re.MULTILINE)
def read_current_version() -> Tuple[str, str]:
"""返回 (当前版本号含V前缀, 构建日期)。"""
text = VERSION_PY.read_text(encoding="utf-8")
m = VERSION_RE.search(text)
if not m:
raise SystemExit(f"无法从 {VERSION_PY} 解析 APP_VERSION")
md = BUILD_DATE_RE.search(text)
return m.group(1), (md.group(1) if md else "")
def parse_semver(ver: str) -> Tuple[int, int, int]:
"""V3.3.3 → (3, 3, 3)。"""
s = ver.lstrip("Vv")
parts = s.split(".")
if len(parts) != 3:
raise SystemExit(f"版本号格式应为 X.Y.Z 或 VX.Y.Z,得到: {ver!r}")
try:
return int(parts[0]), int(parts[1]), int(parts[2])
except ValueError:
raise SystemExit(f"版本号包含非数字部分: {ver!r}")
# ============================================================
# 计算下一个版本号
# ============================================================
def compute_next(current: str, level: str) -> str:
"""level ∈ {major, minor, patch}。返回带 V 前缀的下一版本号。"""
major, minor, patch = parse_semver(current)
if level == "major":
return f"V{major + 1}.0.0"
if level == "minor":
return f"V{major}.{minor + 1}.0"
if level == "patch":
return f"V{major}.{minor}.{patch + 1}"
raise SystemExit(f"未知 level: {level!r}")
# ============================================================
# 文件改写
# ============================================================
def update_version_py(new_ver: str, build_date: str, *, dry_run: bool) -> None:
text = VERSION_PY.read_text(encoding="utf-8")
new_text = VERSION_RE.sub(f'APP_VERSION = "{new_ver}"', text, count=1)
new_text = BUILD_DATE_RE.sub(f'APP_BUILD_DATE = "{build_date}"', new_text, count=1)
if new_text == text:
print(f" [skip] {VERSION_PY.relative_to(PROJECT_ROOT)} 内容未变")
return
if dry_run:
print(f" [dry-run] {VERSION_PY.relative_to(PROJECT_ROOT)}: APP_VERSION={new_ver} APP_BUILD_DATE={build_date}")
return
VERSION_PY.write_text(new_text, encoding="utf-8")
print(f" [ok] {VERSION_PY.relative_to(PROJECT_ROOT)}: APP_VERSION={new_ver}")
PYPROJECT_VER_RE = re.compile(r'^version\s*=\s*"[^"]+"', re.MULTILINE)
def update_pyproject(new_ver: str, *, dry_run: bool) -> None:
if not PYPROJECT_TOML.exists():
print(f" [skip] {PYPROJECT_TOML.relative_to(PROJECT_ROOT)} 不存在")
return
text = PYPROJECT_TOML.read_text(encoding="utf-8")
# PEP 440 不支持 V 前缀
pep440 = new_ver.lstrip("Vv")
new_text = PYPROJECT_VER_RE.sub(f'version = "{pep440}"', text, count=1)
if new_text == text:
print(f" [skip] {PYPROJECT_TOML.relative_to(PROJECT_ROOT)} 中未找到 version 字段或值未变")
return
if dry_run:
print(f" [dry-run] {PYPROJECT_TOML.relative_to(PROJECT_ROOT)}: version={pep440}")
return
PYPROJECT_TOML.write_text(new_text, encoding="utf-8")
print(f" [ok] {PYPROJECT_TOML.relative_to(PROJECT_ROOT)}: version={pep440}")
CHANGELOG_UNRELEASED_RE = re.compile(
r"^## \[Unreleased\]\s*$",
re.MULTILINE,
)
def update_changelog(new_ver: str, build_date: str, *, dry_run: bool) -> None:
"""把 [Unreleased] 段改名为 [<新版本>] — <日期>,并在前面新建一个空 [Unreleased] 段。
bottom 的对比链接也顺手添加。
"""
if not CHANGELOG_MD.exists():
print(f" [skip] {CHANGELOG_MD.relative_to(PROJECT_ROOT)} 不存在")
return
text = CHANGELOG_MD.read_text(encoding="utf-8")
if not CHANGELOG_UNRELEASED_RE.search(text):
print(f" [skip] CHANGELOG.md 中未找到 [Unreleased] 段,跳过")
return
# 1) 把 ## [Unreleased] → ## [<new_ver>] — <date>,并在其上方插入新的 ## [Unreleased]
replacement = f"## [Unreleased]\n\n## [{new_ver}] — {build_date}"
new_text = CHANGELOG_UNRELEASED_RE.sub(replacement, text, count=1)
# 2) 维护底部的对比链接:把现有的 [Unreleased]: ...compare/<old>...HEAD 改成新的,
# 并新增 [<new_ver>]: ...compare/<old>...<new_tag>
cur_ver, _ = read_current_version()
cur_tag = "v" + cur_ver.lstrip("Vv")
new_tag = "v" + new_ver.lstrip("Vv")
# 替换 Unreleased 链接
unreleased_link_re = re.compile(
r"^\[Unreleased\]:\s*(.+?compare/)([^.]+)(\.\.\.HEAD)\s*$",
re.MULTILINE,
)
m = unreleased_link_re.search(new_text)
if m:
prefix = m.group(1)
# 替换为指向新 tag
new_unreleased = f"[Unreleased]: {prefix}{new_tag}...HEAD"
new_text = unreleased_link_re.sub(new_unreleased, new_text, count=1)
# 在 Unreleased 链接行下方插入新的对比链接
# 形如: [<new_ver>]: <prefix><cur_tag>...<new_tag>
new_compare_line = f"[{new_ver}]: {prefix}{cur_tag}...{new_tag}"
# 找到 [Unreleased]: 那一行,在其下一行插入
new_text = new_text.replace(
new_unreleased,
f"{new_unreleased}\n{new_compare_line}",
1,
)
if dry_run:
print(f" [dry-run] {CHANGELOG_MD.relative_to(PROJECT_ROOT)}: 重命名 [Unreleased] 为 [{new_ver}],新增空 [Unreleased]")
return
CHANGELOG_MD.write_text(new_text, encoding="utf-8")
print(f" [ok] {CHANGELOG_MD.relative_to(PROJECT_ROOT)}: [Unreleased] → [{new_ver}]")
# ============================================================
# git tag
# ============================================================
def create_git_tag(new_ver: str, *, dry_run: bool) -> None:
tag = "v" + new_ver.lstrip("Vv")
msg = f"Release {new_ver}"
cmd = ["git", "tag", "-a", tag, "-m", msg]
if dry_run:
print(f" [dry-run] git tag: {tag}")
return
res = subprocess.run(cmd, cwd=PROJECT_ROOT, capture_output=True, text=True)
if res.returncode == 0:
print(f" [ok] git tag: {tag}")
else:
# 已存在的 tag 不算致命错误,但要提醒
if "already exists" in (res.stderr or ""):
print(f" [warn] git tag {tag} 已存在")
else:
print(f" [err] git tag 失败: {res.stderr.strip()}")
# ============================================================
# main
# ============================================================
def main(argv: Optional[list[str]] = None) -> int:
parser = argparse.ArgumentParser(
description="单入口 bump 项目版本号(version.py + pyproject.toml + CHANGELOG.md + git tag)。",
)
parser.add_argument(
"level",
choices=["major", "minor", "patch", "set"],
help="bump 级别;'set' 时需要再传一个版本号参数",
)
parser.add_argument(
"version",
nargs="?",
help="当 level=set 时使用,例如 V3.5.0",
)
parser.add_argument(
"--no-tag",
action="store_true",
help="只更新文件,不创建 git tag",
)
parser.add_argument(
"--dry-run",
action="store_true",
help="只打印将要做什么,不实际写入",
)
args = parser.parse_args(argv)
cur_ver, cur_date = read_current_version()
print(f"当前版本: {cur_ver} (build {cur_date or 'n/a'})")
if args.level == "set":
if not args.version:
print("ERROR: level=set 需要传第二个参数(版本号)", file=sys.stderr)
return 1
# 规范化前缀
new_ver = args.version
if not new_ver.startswith(("V", "v")):
new_ver = "V" + new_ver
# 验证格式
parse_semver(new_ver)
else:
new_ver = compute_next(cur_ver, args.level)
new_date = _dt.date.today().isoformat()
print(f"目标版本: {new_ver} (build {new_date})")
print()
update_version_py(new_ver, new_date, dry_run=args.dry_run)
update_pyproject(new_ver, dry_run=args.dry_run)
update_changelog(new_ver, new_date, dry_run=args.dry_run)
if not args.no_tag:
create_git_tag(new_ver, dry_run=args.dry_run)
print()
if args.dry_run:
print("[dry-run] 没有写入任何改动。")
else:
print("✓ 完成。建议下一步:")
print(" 1. 编辑 CHANGELOG.md,把本版的 Added/Fixed/Changed 写到对应小节")
print(f" 2. git commit -am 'chore(release): bump version to {new_ver}'")
if not args.no_tag:
print(" 3. git push --follow-tags")
else:
print(f" 3. git tag -a v{new_ver.lstrip('Vv')} -m 'Release {new_ver}'")
print(" 4. git push --follow-tags")
return 0
if __name__ == "__main__":
sys.exit(main())