MySQLTuner 本地开发同步工作流：版本一致性、Changelog 自动整理与发布前自检实战

• 数据库
• 运维

本篇指南聚焦 MySQLTuner-perl 仓库中面向开发者的本地同步自动化工作流（Local Developer Sync Workflow），讲解如何通过一条命令完成版本一致性校验、Changelog 自动整理、发布说明（Release Notes）再生成、单元测试审计与 Git 交付。读完本文，你将掌握该工作流的完整执行管线、底层脚本实现原理，以及如何在推送远程仓库前用同一套标准自检自己的开发分支。

工作流定位：一次调用，四项保障

在 MySQLTuner-perl 中，本地开发同步工作流由 .agent/workflows/local-dev-sync.md 定义。它的元数据（front-matter）明确了触发方式与定位：

• trigger：explicit_call，即由开发者显式调用，而非由事件或定时器自动触发；
• category：tool，属于开发工具类流程；
• description：同步开发者更改、运行单元测试、更新 Changelog 与发布说明。

其设计初衷（Rationale）非常直白：在推送远程仓库之前，确保分支历史干净同步、发布文档准确、单元测试全部通过。也就是说，它把"提交前该做的事"固化成一条可重复执行的自动化管线，避免人工遗漏版本号、漏写 Changelog 或带病提交。

一键执行：perl build/dev_sync.pl

工作流的实现部分给出的命令极其简单：

perl build/dev_sync.pl

这个入口位于仓库根目录下的 build/dev_sync.pl。从源码结构看，它是一个典型的 Perl 顺序编排脚本：main()函数（第 149 行起）将整个同步过程划分为4 个阶段，任何一个阶段失败都会以非零退出码（exit(1)）立即终止，从而保证"要么全部完成，要么什么都不推"。

脚本通过log_msg输出带时间戳的[DEV-SYNC]前缀日志，方便开发者追踪每一步：

sub log_msg { my ($msg) = @_; my $timestamp = strftime("%Y-%m-%d %H:%M:%S", localtime); print "[$timestamp] [DEV-SYNC] $msg\n"; }

四个阶段分别为：

1. 版本一致性检查：调用perl tests/version_consistency.t；
2. 提交提取与文档更新：解析最近 Conventional Commits，更新Changelog，再调用python3 build/release_gen.py重新生成发布说明；
3. 单元测试审计：调用perl build/audit_tests.pl运行全部测试；
4. 提交与推送：把变更的发布文件 commit 并 push 到origin。

阶段 1：版本一致性检查

脚本首先运行 tests/version_consistency.t，该测试以 CURRENT_VERSION.txt（当前内容为2.9.1）作为唯一版本事实来源（source of truth），然后逐一对齐以下 6 处版本字符串：

任何一处不匹配，version_consistency.t都会给出对应的is()断言失败，进而导致dev_sync.pl在第 1 步即中止：

my $res = system("perl tests/version_consistency.t"); if ($res != 0) { log_msg("FAIL: Version consistency checks failed!"); exit(1); }

这与 COMMIT_AND_RELEASE.md 中"同步版本号"的 6 个位置清单完全对应，也印证了版本一致性检查是发布纪律的第一道闸门。

阶段 2：提取提交，更新 Changelog 与发布说明

通过版本检查后，脚本读取CURRENT_VERSION.txt得到当前版本，并用git describe --tags --abbrev=0找到上一个标签作为对比基准（若仓库尚无标签则回退到master）：

my $prev_tag = qx(git describe --tags --abbrev=0 2>/dev/null); chomp($prev_tag); if (!$prev_tag) { $prev_tag = "master"; } log_msg("Comparing current branch against base ref: $prev_tag"); my @commits_raw = qx(git log $prev_tag..HEAD --pretty=format:%s);

随后用正则^(\w+)(?:\(([^)]+)\))?(!)?:\s*(.*)解析每条提交信息，将其规范化为- type(scope): desc的 Changelog 条目（类型转为小写，!破坏性提交标记被识别但条目格式中不带感叹号）：

if ($line =~ /^(\w+)(?:\(([^)]+)\))?(!)?:\s*(.*)/) { my $type = lc($1); my $scope = $2; my $desc = $4; $desc =~ s/^\s+|\s+$//g; my $scope_str = $scope ? "($scope)" : ""; push @new_items, "- $type$scope_str: $desc"; }

这解释了为什么仓库要求所有提交遵循 Conventional Commits 规范——它不仅是提交纪律，更是 Changelog 自动生成的数据源。

去重与按类别排序

update_changelog_file（第 82 行起）定位当前版本块，把既有条目与新提取条目合并，然后交给process_items处理。其中包含一个值得注意的模糊去重算法：先把字符串小写并剥离所有非字母数字字符（normalize），再通过"完全相等"或"互为子串"（index($a, $b) != -1）判断重复，避免同一功能被重复记录。

排序则严格按 Conventional Commit 类别赋予优先级：

my %categories = ( 'chore' => 1, 'feat' => 2, 'fix' => 3, 'test' => 4, 'ci' => 5, );

未在上述白名单中的类型统一按99排序，落在最后；同类之间再按字典序（cmp）排列。这也是工作流"Verification"清单中Changelog 按 Conventional Commit 类别排序的实现来源。打开仓库根目录的 Changelog 可以看到2.9.1版本块正是以chore、feat、fix、test、ci的顺序呈现。

若当前版本头在 Changelog 中不存在，脚本还会自动在第一个版本头之前插入新的版本块（if (!$found_version)分支），实现"新版本自动建档"。

再生成发布说明

Changelog 更新后，脚本调用 build/release_gen.py：

my $rel_notes_res = system("python3 build/release_gen.py"); if ($rel_notes_res != 0) { log_msg("FAIL: Release notes generation failed!"); exit(1); }

从源码看，release_gen.py以CURRENT_VERSION.txt为版本来源、以Changelog为数据源，用正则(\d+\.\d+\.\d+) (\d{4}-\d{2}-\d{2})切分各版本块，再通过git log在master/origin/master、上一标签或当前分支之间提取提交记录，最终把"版本摘要 + 提交差异"编译写入 releases/ 目录下的v[VERSION].md文件（例如 releases/v2.9.1.md）。这正是工作流验证清单中releases/v[VERSION].md与最新条目匹配的保障。

阶段 3：单元测试审计

发布文档就绪后，脚本进入测试关卡，调用 build/audit_tests.pl：

my $test_res = system("perl build/audit_tests.pl"); if ($test_res != 0) { log_msg("FAIL: Unit tests failed!"); exit(1); }

audit_tests.pl比裸prove多做两件事：

• 编译期静态检查：对mysqltuner.pl、tests/MySQLTuner/TestHelper.pm 以及全部tests/*.t逐个执行perl -I. -Itests -wc，捕获语法错误、Compilation failed、Undefined subroutine等硬错误；
• 测试执行与输出审计：默认运行prove -j4 -r tests/，并扫描输出中的隐蔽 Perl 警告、拼写错误与运行时问题（支持--debug/--verbose参数切换详细模式）。

也就是说，这一阶段同时承担了"测试是否通过"与"代码是否干净"的双重校验。

阶段 4：提交与推送

最后一步只处理与发布文档相关的变更。脚本用git status --porcelain过滤出Changelog与releases/路径下的改动文件，逐个git add，然后以固定信息docs: regenerate release notes提交：

my @status_lines = qx(git status --porcelain); ... if ($line =~ /(Changelog|releases\/)/) { ... push @modified_files, $file; } ... my $commit_res = system("git commit -m \"docs: regenerate release notes\"");

若没有文档改动，则跳过提交（"No documentation changes to commit."），但推送仍会继续。推送使用当前分支的 refspec（refs/heads/<branch>，检出状态下为HEAD），直接git push origin到远程：

my $branch = qx(git branch --show-current); my $refspec = $branch ne "HEAD" ? "refs/heads/$branch" : "HEAD"; my $push_res = system("git push origin \"$refspec\"");

验证清单：如何确认同步成功

工作流文档在 "Verification" 一节给出了六条明确的成功判据，也是开发者自查时对照的验收标准：

1. 脚本返回退出码 0（exit 0收尾，任何失败阶段都以exit(1)中断）；
2. 所有版本文件确认一致（version_consistency.t六处断言全部通过）；
3. Changelog已更新，并按 Conventional Commit 类别排序（chore→feat→fix→test→ci）；
4. releases/v[VERSION].md与最新条目匹配（release_gen.py已重新生成）；
5. 所有本地单元测试通过（audit_tests.pl的编译检查与prove执行均无失败）；
6. 变更的发布文件已提交并推送到origin。

运行前置条件与失败处理

从脚本依赖可以梳理出运行该工作流的实际环境要求：

• Perl 环境：脚本本身、version_consistency.t、audit_tests.pl均为 Perl 实现；
• Python 3：release_gen.py依赖python3，缺失会导致第 2 阶段失败；
• Git 仓库状态：需要已配置origin远程；若分支尚未包含任何标签，脚本会自动退化为与master对比；
• 工作目录：脚本通过abs_path(dirname(__FILE__) . '..')自行定位仓库根目录，因此可从任意子目录调用，不依赖调用者当前所在路径。

值得强调的是：该脚本的提交与推送动作是设计内行为——它会在本地创建docs: regenerate release notes提交并推送到origin。如果你只想本地演练而不想推送，需要自行控制（例如运行到推送前手动中断），仓库文档中并未提供跳过推送的开关。此外，Changelog 去重采用子串匹配策略，极端情况下可能将语义相近但不同的条目误判为重复，人工复核 Changelog 仍是推荐做法。

与周边发布工作流的协作

本地同步工作流并非孤立存在。从 .agent/workflows/ 目录可以观察到一组相互衔接的 Agent 工作流：

• release-notes-gen.md：独立生成/更新发布说明，对应dev_sync.pl中调用release_gen.py的环节；
• release-preflight.md：发布前预检（版本一致性、发布说明存在性、Conventional Commits 合规、make check-tidy格式化、冒烟测试），对应 COMMIT_AND_RELEASE.md 中描述的 Preflight 流程；
• release-manager.md：最终打标签（git tag -a vX.XX.XX）与推送，详见 documentation/specifications/release_manager_specification.md；
• doc-sync.md：文档同步，与发布文档生成互补。

从工作流链看，dev_sync负责日常开发分支上的同步与自检，release-preflight与release-manager负责发布阶段的最终校验与打标签，二者形成"日常 → 发布"的两级质量闸门。与此同时，Makefile 中的make unit-tests、make generate_usage、make increment_sub_version等目标也为人工执行对应的原子步骤提供了等价入口。

小结

MySQLTuner 的本地开发同步工作流把"版本对齐、Changelog 整理、发布说明再生成、测试审计、Git 交付"压缩为一条perl build/dev_sync.pl命令。它的核心设计思想值得借鉴：以CURRENT_VERSION.txt为唯一版本事实来源、以 Conventional Commits 为 Changelog 数据源、以退出码为硬性门禁，确保任何推送到远程的代码都经过一致的自动化工序。对于参与 MySQLTuner 开发的贡献者而言，这条工作流既是效率工具，也是与仓库发布纪律（见 COMMIT_AND_RELEASE.md）对齐的最低验收标准。

• 数据库
• 运维