sequential_attention 项目版本演进与 CHANGELOG 发布流程指南
sequential_attention 项目版本演进与 CHANGELOG 发布流程指南
导读
本文以 sequential_attention/CHANGELOG.md 为骨架,系统讲解该特征选择项目的版本记录规范、两个正式版本(v0.1.0 与 v0.2.0)的实际演进内容,以及遵循 keepachangelog 标准发布新版本的具体操作步骤。读完本文,你将掌握如何解读该仓库的版本历史、如何把代码变更(如新增算法实验)正确登记到 CHANGELOG 中,并理解 CHANGELOG.md 与源码 __version__、打包配置之间的联动机制。
一、CHANGELOG 的定位与规范基础
sequential_attention/CHANGELOG.md 是该项目的版本变更记录文件,其头部注释明确了两个核心设计目标:
- 支持自动化发布:文件格式遵循 keepachangelog 标准(至少是标题格式),使得发布说明能够在 GitHub Actions 自动化发布流程中被自动解析,生成 release notes;
- 可点击的标题:按标准格式书写的
## [版本号] - 日期标题,在渲染后的 Markdown 中呈现为可点击的锚点,便于读者在多个版本说明之间快速跳转。
从仓库实际内容看,CHANGELOG.md 与打包系统是配套的:pyproject.toml 中通过 dynamic = <a href="https://link.gitcode.com/i/45de900c9610b8246cd854feede59eee" target="_blank">"version"] 声明版本号由 sequential_attention.__version__ 自动推导,而 [sequential_attention/init.py 中的注释明确写道:每次提升 __version__ 都会触发新的 PyPI 发布,同时必须同步更新 CHANGELOG.md。也就是说,CHANGELOG 不是可有可无的文档,而是发布流水线的一部分。
二、版本历史解读:两次发布背后的功能演进
当前 CHANGELOG.md 记录的版本历史非常精简,但每一条都对应着仓库中的实质性代码模块:
2.1 [0.1.0] - 2022-01-01:Initial release
这是项目的首次正式发布,对应的是论文《Sequential Attention for Feature Selection》(Yasuda 等人)的核心算法实现。本次发布包含的功能实体:
- 核心模块 sequential_attention/sequential_attention.py:
SequentialAttention类,用注意力机制高效实现经典贪心前向选择算法。其构造参数包括num_candidates(候选特征总数)、num_candidates_to_select(要选出的特征数)、num_candidates_to_select_per_step(每步选出数量,默认 1)、start_percentage(默认 0.1)、stop_percentage(默认 1.0)与reset_weights(默认 True)。前向调用接收training_percentage(0~1 之间单调递增的训练进度),返回一个和为 1 的注意力权重向量,并用selected_features变量累加记录已选特征; - 实验框架 sequential_attention/experiments/run.py:基于 absl flags 的完整实验入口,支持
sa / lly / seql / gl / omp五种特征选择算法在mnist / fashion / isolet / mice / coil / activity六个数据集上运行; - 对比基线 sequential_attention/sequential_attention/benchmarks/:收录了 Orthogonal Matching Pursuit(orthogonal_matching_pursuit.py)、Sequential Lasso(sequential_lasso.py)以及 Liao-Latty-Yang 注意力掩码(liao_latty_yang.py)等对照算法。
从源码结构可以推断,v0.1.0 发布时点对应论文复现实验的完整交付,即"Simple Sequential Attention"形态。
2.2 [0.2.0] - 2023-08-03:Added Ensembled Sequential Attention experiments
第二次发布只记录了一条变更,却对应着一个全新的独立功能目录 ensembled_sequential_attention/,其中包括:
- 对比研究 Notebook SequentialAttentionTimeTracking.ipynb:在低数据量(20%/40%/60% 随机子样本)与低特征量两种实验设置下,对 Simple Sequential Attention 与 Intermediate(Ensembled)Sequential Attention 进行对比研究,目标是降低所需数据量并产出更好、更稳定的结果;
- 算法扩展说明:Notebook 中新增了
IntermediateSA方法——由 K 个 worker 组成的集成,每个 worker 各自给出下一批最优特征(示例中为 20 个),在每个检查点由集成投票选出共同掩码,随后所有 worker 以该共同先验继续推进,直到覆盖全部目标特征集大小(如 [20, 30, 40, 50])。核心实现见get_masks_fn_intermediate_sa(),其投票逻辑基于model.sa.selected_features的 top-k 索引统计; - 实验结果图片:目录下的三张结果图(见下文第四节)展示了该方法在特征质量与稳定性上的改进。
这一版本的演进脉络清晰:从"单个模型顺序挑选特征"升级到"多个模型投票集成挑选特征",即 Ensembled Sequential Attention。
三、发布新版本的标准操作流程
CHANGELOG.md 头部注释给出了严格的发布步骤,这是 keepachangelog 规范在项目中的落地实践。假设当前版本为 1.0.0,需要发布 2.0.0:
3.1 第一步:新增版本标题并迁移变更
在文件顶部([Unreleased] 之下)创建新的标题行,并把当前 [Unreleased] 中积累的变更说明移入新版本:
## [Unreleased]
## [2.0.0] - YYYY-MM-DD
* <此处填写自 1.0.0 以来的全部用户可见变更>
日期格式为 YYYY-MM-DD,与 keepachangelog 标准保持一致。
3.2 第二步:更新文件末尾的版本链接
在文件末尾需要完成两项链接维护:
- 定义新版本的比较链接,用于查看从旧版本到新版本的完整代码差异:
[2.0.0]: https://github.com/google-research/sequential_attention/compare/v1.0.0...v2.0.0
- 更新
[Unreleased]的链接基线,把v1.0.0...HEAD改为v2.0.0...HEAD:
[Unreleased]: https://github.com/google-research/sequential_attention/compare/v2.0.0...HEAD
3.3 第三步:同步提升源码版本号
根据 sequential_attention/init.py 中的约定,发布动作与 __version__ 直接挂钩:修改该文件中的 __version__ = '0.1.0' 为新的版本号(如 0.2.0),flit 构建后端会据此自动生成包版本(见 pyproject.toml 的 dynamic = ["version"]),PyPI 发布流程随之触发。因此,发布新版本 = 更新 CHANGELOG + 更新 __version__,两步缺一不可。
四、0.2.0 新增内容的实证:Ensembled Sequential Attention 关键结果
CHANGELOG.md 对 0.2.0 的条目虽然只有一句话,但其背后的实验结论在 ensembled_sequential_attention/README.md 中有明确数据支撑,可以作为理解该版本价值的实证材料:
- 在部分数据集上,即使进一步削减特征数量,仍能保持同等质量;
- Intermediate(Ensembled)Sequential Attention 比 Simple Sequential Attention 更稳定(多次随机初始化下精度波动更小);
- 在论文的同一实验设置下(50 个特征、Activity 数据集),Intermediate Sequential Attention 的测试集准确率为 93.22%,比 Simple SA 的 92.54% 高出 0.7%,而用全部 561 个特征训练的全量模型为 94.47%——即仅用约 9% 的特征就逼近全量模型的精度。
上图为特征选择质量对比:在多种特征集大小下,Sequential Attention 明显优于随机特征选择基线,这也是 v0.1.0 核心算法有效性的直观证据。
上图展示的是 v0.2.0 的核心增量——集成式(Intermediate)注意力在多次随机初始化下的精度分布更集中、方差更小,即"更稳定"这一结论的实验来源。两张图分别对应 CHANGELOG.md 中两次发布的核心内容,可作为阅读版本记录时的可视化参考。
五、版本记录与仓库结构的对照速查
为了便于检索和引用,这里将 CHANGELOG 条目与仓库文件建立一一对应关系:
| CHANGELOG 条目 | 对应功能 | 仓库位置 |
|---|---|---|
| 0.1.0] Initial release | SequentialAttention 核心模块 | [sequential_attention/sequential_attention.py |
| 0.1.0] Initial release | 实验入口与超参数配置 | [sequential_attention/experiments/run.py、hyperparams_sa.py |
| [0.1.0] Initial release | OMP / Sequential Lasso / LLY 对比基线 | sequential_attention/sequential_attention/benchmarks/ |
| [0.2.0] Ensembled 实验 | 集成式注意力对比研究 Notebook | SequentialAttentionTimeTracking.ipynb |
| [0.2.0] Ensembled 实验 | 实验结果说明与图表 | ensembled_sequential_attention/README.md |
此外,仓库根目录的 run.sh 提供了一条完整的本地复现链路:创建 virtualenv → pip install --editable . 安装包 → 运行 get_all_data.sh 下载活动、COIL、ISOLet、Mice 数据集 → 执行 python -m sequential_attention.experiments.run --num_epochs=3 --data_name=mice 快速验证;完整实验套件则可通过 python -m sequential_attention.experiments.experiments 运行,其内部会依次调度 run.py 并在 /tmp/model_dir 下按 数据集/experiment_seed_{1..5} 组织 5 个随机种子的结果,最终由 read_results.py 汇总各次实验的验证/测试准确率。
结语
sequential_attention/CHANGELOG.md 虽然篇幅简短,却是理解整个项目演进史与发布机制的入口:v0.1.0 承载了核心的 Sequential Attention 特征选择算法与完整实验框架,v0.2.0 则引入了 Ensembled Sequential Attention 这一集成扩展。遵循 keepachangelog 标准的标题格式、版本链接维护方式,以及与 __version__ 和 flit 打包的联动约定,共同构成了该项目"代码变更 → 版本记录 → 自动发布"的完整闭环。当你在该仓库中提交新功能时,按第三节的流程同步维护 CHANGELOG 与版本号,即可保证发布说明的准确与可追溯。

