SemVer change governance
SemVer change governance 是一套可选的 house policy,用于在 owner 明确要求时分类一个 compatibility scope 对 public API 与 persistent state 合同的版本影响。
- 交付
- 设计
- 工具
目录
Definition
SemVer change governance 是一套可选的 house policy,用于在 owner 明确要求时分类一个 compatibility scope 对 public API 与 persistent state 合同的版本影响。它可以产出 patch、minor 或 major 的 planned、current 与 verified compatibility conclusion,以及结论所需的证据;不是对行业标准的断言,也不是版本号、release target 或发布资格的来源。
本 Topic 不拥有版本号数字来源、trusted baseline、tag、label、质量门禁、任务、计划、PR、CI 或发布编排,也不规定怎样实施 state migration。Persistent-state migrations 负责迁移、rollout 与恢复的实现政策;PR label release 等明确采用兼容协议的 Topic 可以消费本 Topic 的分类,但必须由自己的 project contract 声明映射和持久化范围。
Manual version release delivery 是独立的 target-selection route:它只接收 owner 提供的一个 release target,并由执行端根据 trusted final baseline 解析 canonical version。对 target-only manual release 项目,SemVer classification、assessment record、release-unit aggregation 和 candidate binding 都不是 target input、required check、release eligibility 或 durable release state。
When to use
当变更可能改变 public API,或改变会由后续程序读取的 persistent state,且 owner、项目合同或兼容性审查明确要求分类时使用。实现前可以记录 planned impact;一旦范围出现新 surface、原先假设失效或兼容性边界改变,可以 reclassify;验证阶段以测试或其他可核查证据形成 verified impact。
仅改内部实现且能证明 public API 与 persistent state 均未受影响时,也可以留下 optional patch 判断与证据。只需要 version identity、tag/label、trusted baseline、target selection 或 release orchestration 的任务不应命中本 Topic;target-only manual release 不因为采用 SemVer grammar 就自动启用本 Topic。
Habits / defaults
- 先声明兼容性范围,再决定是否记录。
skills/policies/semver-change-governance/assets/templates/version-impact-record.example.json是可选的 compatibility assessment template;它不要求每个 PR 一个文件,不要求 candidatebase_sha/source_sha,也不定义 manual release 输入。 - API 与 state 分开判断。
public_api与persistent_state必须有各自的 rationale、supported range 和 evidence;migration mechanics 属于Persistent-state migrations,不能因数据库文件、diff 大小或迁移数量直接推导 API impact。 - 分类不自动选择 target。
patch、minor、major是兼容性结论,不是本 Topic 的 exact version 或 Manual release input。任何 adopter-specific aggregation 或 label projection 都必须写入 adopter 自己的 Policy,并明确不影响 target-only manual release。 - release-unit aggregation 是可选扩展。 如果另一个项目明确把多个 compatibility assessments 归入一个 release unit,可以在自己的 contract 中定义最高影响的计算和 evidence;该聚合不是本 Topic 的默认 durable state,也不是本项目 Manual release 的前置条件。
- 在 scope 漂移时重新审查。 planned、current 与 verified 结论应能说明支持范围、理由与测试证据;如果新增 public surface、改变 state reader 或缩小兼容范围,应重新分类,而不是沿用早期结论。
- 不假定交付系统。 本 Topic 可以独立用于 ADR、设计审查、release note 或项目自己的 compatibility record,不要求 CI、PR、tag、数据库、供应商或特定语言;project contract 需要什么证据,应由 adopter 自己声明。
Reference implementations
projects/resume.md 是一个独立项目的历史 checked-in implementation evidence:它展示了 candidate-bound impact 与 manual consumer 的旧集成方式,不能作为 target-only manual release 的默认路径,也不代表本仓库已经采用该集成。medium confidence 仍然合适,因为跨项目可复用的 compatibility governance 证据有限。
skills/style-playbook/references/topics/persistent-state-migrations/TOPIC.md:负责 durable state 的迁移操作、数据库 DDL/DML 边界、rollout、恢复与每个分类所需的 state 验证;它不替代此处的 version-impact classification。skills/style-playbook/references/topics/pr-label-release/TOPIC.md:仅供明确采用 PR-label release protocol 的项目消费兼容性结论;该 Topic 不适用于本项目的 target-only manual release。projects/fusb302-rs.md:记录 crate 的 manifest、tag 与发布媒介事实,但不证明本 Topic 的 public API/state 分类政策已经被采用。
Failure modes
- 把可选 compatibility assessment 当成 Manual target、release eligibility 或 per-PR required evidence,会让兼容性治理越过边界;target-only manual release 应只读取 owner target 和 trusted final baseline。
- 在实现结束后才第一次判断 impact,或在 scope drift 后沿用早期结论,会漏掉新增 public surface 或 state contract;应在 project contract 要求的阶段留下理由并复核证据。
- 把 verified impact 误当成 exact version,或让 Agent 依据 baseline 提前替换 owner 的 symbolic target,会越过 intent selection 边界;exact version 与 target resolution 属于 Manual release policy。
- 以 PR 大小、label、版本号可用性或迁移文件数量代替兼容性判断,会把交付机制误当成政策证据;应分别判断 public API 与 persistent state。
- 因 Minor 的 state incompatibility 自动标记为 public API Major,或因 API 未变而忽略 state compatibility,都会混淆两条合同;分别记录后再由 adopter 的 release-unit contract 决定是否需要聚合。
- 把本 Topic 扩展为数据库 DDL、DML/backfill、rollback 或 forward repair 的操作手册,会与
Persistent-state migrations重叠;这里只记录这些操作必须满足的版本合同与证据。 - 假定所有项目都经由某种任务、规划、PR、CI 或 release 系统,或为此引入厂商依赖,会把可移植治理误写成特定工作流。
Evidence index
projects/resume.mdskills/policies/semver-change-governance/SKILL.mdskills/policies/semver-change-governance/assets/templates/version-impact-record.example.jsonskills/style-playbook/references/topics/persistent-state-migrations/TOPIC.mdskills/style-playbook/references/topics/pr-label-release/TOPIC.mdprojects/fusb302-rs.md
相关内容
FUSB302 Rust PHY Driver
项目实践fusb302 是面向 FUSB302B/FUSB302BMPX 的 no_std Rust USB Type-C 和 USB Power Delivery BMC PHY driver。它提供寄存器级控制、Type-C 电气控制、VBUS comparator、interrupt/FIFO 和 PD packet transport;README.
Resume
项目实践Resume 是一个 Astro 静态简历站点:本地完整构建用于打印与视觉检查,publish artifact 提供 value-free loading shell,再由 Edge Function 在访问验证后返回结构化简历内容与 PDF 能力(README.md、astro.config.mjs、src/data/resume.ts)。
semver-change-governance
规则Apply optional SemVer compatibility classification when a change may alter a public API or persistent state; it does not select manual release targets.