43-EFT.WP.Data.DatasetCards v1.0 | 第14章 发布与版本化

目录 ／ 文档-技术白皮书 ／ 43-EFT.WP.Data.DatasetCards v1.0

第14章 发布与版本化

I. 章节目的与范围

II. 术语与依赖

• 术语来源：遵循《EFT.WP.Core.Terms v1.0》，本章仅增量定义发布与版本化字段。
• 依赖卷：数据契约/导出：《Core.DataSpec v1.0》；计量/量纲校核：《Core.Metrology v1.0》；切分与分发：第11章；质量与基线：第12章；隐私与合规：第13章；引用与版本携带：引用规范 v0.1。

III. 字段与结构（规范性）

release:

channel: "stable" # alpha | beta | rc | stable | yanked

version: "v1.0.0" # 语义化版本：vMAJOR.MINOR.PATCH

date: "2025-09-20"

tag: "eift-foo-v1.0.0" # Git/对象存储标签

compatibility:

baseline: "v1.*" # 对外承诺的稳定线

backwards: "minor" # backwards: none|patch|minor

artifacts: # 与 export_manifest 对表

- {path:"dataset_card.yaml", sha256:"..."}

- {path:"splits/train.index", sha256:"..."}

- {path:"packages/train-000.tgz", sha256:"..."}

checks:

schema_ok: true

lint_ok: true

check_dim_ok: true

quality_gates_ok: true

notices: # 公告口径（撤回/更正/限制说明）

type: "release" # release | correction | withdrawal

summary: "initial stable"

see:

- "EFT.WP.Core.DataSpec v1.0:EXPORT"

- "EFT.WP.Core.Metrology v1.0:check_dim"

versioning:

scheme: "semver" # 语义化版本

stability_line: "v1.*" # 对外引用建议

policy:

major: "breaking" # 断裂变更才提升 MAJOR

minor: "additive" # 向后兼容新增/字段可选化

patch: "fix" # 修复/文案更正，不改语义

deprecation:

announce_in: ["dataset_card.yaml", "export_manifest"]

grace_cycles: 1 # 至少保留一个 MINOR 周期

withdrawal:

allowed: true

reasons: ["legal","safety","integrity","privacy"]

mirror_tombstone: true # 镜像保留墓碑与公告

（release.* 与 versioning.* 字段用于卡片与门户同步，发布产物在 export_manifest 中逐项可验。）

IV. 语义化版本与稳定线

1. 版本格式：vMAJOR.MINOR.PATCH（如 v1.2.3）。
2. 提升规则：
   • MAJOR：发生断裂变更（必填字段语义改变/删除、分割索引格式变化）。
   • MINOR：向后兼容新增（新增可选字段、补充映射、增加示例/分片）。
   • PATCH：修复与微更正（文本/注释/校验脚本修复），不改语义与结构。
3. 稳定线：对外引用推荐指向 v1.* 稳定线；论文/基准报告建议固定到 次版本（如 v1.2.*）以确保可复现。

V. 兼容性矩阵与弃用策略

1. 兼容性矩阵：
   • Schema：minor+patch 兼容；major 可能断裂。
   • 指标与评测协议：新增不破坏既有；删除/语义变化需 major。
   • 切分索引：冻结后不可变更；如需变更必须提升 major 并提供迁移脚本。
2. 弃用（Deprecation）：在 dataset_card.yaml 与 export_manifest.references[] 公告弃用条目与替代路径；至少给予 grace_cycles >= 1 的迁移期。

VI. 撤回（Withdrawal）与更正（Correction）

• 撤回条件：法律/安全/完整性/隐私重大风险；release.channel="yanked"，镜像保留墓碑与公告。
• 更正流程：小幅修复以 PATCH 发布；若影响评测可比性，需同时更新 notices.type="correction" 并在质量报告中标注影响范围。

VII. 发布前置检查（Blocking Gates）

• schema_ok、lint_ok、check_dim_ok、quality_gates_ok 全部为 true；
• splits 冻结并与第6–7章采样/清洗审计一致；
• 隐私/伦理与区域合规条款完成校验并在 distribution.regional_compliance[] 体现。

VIII. 导出清单对表（规范性）

export_manifest:

version: "v1.0.0"

artifacts:

- {path:"dataset_card.yaml", sha256:"..."}

- {path:"splits/train.index", sha256:"..."}

- {path:"packages/train-000.tgz", sha256:"..."}

- {path:"quality/summary.csv", sha256:"..."}

references:

- "EFT.WP.Core.DataSpec v1.0:EXPORT"

- "EFT.WP.Core.Metrology v1.0:check_dim"

notices:

- {type:"release", summary:"initial stable", date:"2025-09-20"}

（所有工件必须逐项可验；引用携带卷名+版本+锚点；禁止短码/别名。）

IX. 发布渠道与镜像

• 渠道：alpha（内部试用）、beta（外部反馈）、rc（候选）、stable（稳定）、yanked（撤回）。
• 镜像：至少两处镜像与速率/地区限制；撤回时各镜像统一展示墓碑与指向公告的引用锚点。

X. 机器可读片段（可直接嵌入卡片）

release:

channel: "rc"

version: "v1.1.0-rc1"

date: "2025-10-01"

tag: "eift-foo-v1.1.0-rc1"

compatibility: {baseline:"v1.*", backwards:"minor"}

artifacts:

- {path:"dataset_card.yaml", sha256:"..."}

- {path:"packages/train-000.tgz", sha256:"..."}

checks: {schema_ok:true, lint_ok:true, check_dim_ok:true, quality_gates_ok:true}

notices: {type:"release", summary:"release candidate for v1.1.0"}

versioning:

scheme: "semver"

stability_line: "v1.*"

policy: {major:"breaking", minor:"additive", patch:"fix"}

deprecation: {announce_in:["dataset_card.yaml","export_manifest"], grace_cycles:1}

（与 export_manifest、第11–13章约束及计量/不确定度口径一致。）

XI. 本章合规自检

• 版本号为语义化格式，稳定线明确，对外材料引用 v1.* 或锁定到次版本。
• 兼容性、弃用与撤回策略在卡片与导出清单中公告并可追溯。
• 发布前置检查全部通过；切分/质量/隐私与区域合规一致。
• 导出清单完整可验，所有引用携带“卷名+版本+锚点”，无短码/别名。