diff --git a/docs/governance/decision-log.md b/docs/governance/decision-log.md index 91081254..224cca95 100644 --- a/docs/governance/decision-log.md +++ b/docs/governance/decision-log.md @@ -24,9 +24,11 @@ | 日期 | 门 | 变更 | 决策人 | |---|---|---|---| | 2026-08-23 | D0–D8 | 初次记录;D3(master 部分)、D4、D5(PVR) 为 blocked | cloudQuant(依据 v2 计划实施授权) | +| 2026-08-23 | D3/M4/M6 | M4 观察期完成:五类草稿演练归档(`evidence/m4-draft-pr-drills-20260823.md`),期间发现并修复 5 项缺陷(PR #1/#2/#9/#11);`PR_GOVERNANCE_STRICT=true` 启用;M6 验收矩阵判定 Implementation Complete(`evidence/m6-acceptance-matrix-20260823.md`)。**D3 追记:单一维护者运营约束**——dev/code-opt Ruleset 要求非作者批准,唯一维护者无法自批准,激活将冻结全部合并;推迟至第二维护者确认或 owner 批准 bypass actor 策略。四个 Ruleset 均保持未应用(与 manifest 一致,verify exit 0) | cloudQuant | ## Blocked 解除条件 - **D3-master**:第二位维护者获得 write 权限并在 CODEOWNERS 生效分支完成一次 review drill。 +- **D3-dev/code-opt(运营约束)**:满足其一即可申请激活——(a) 上述第二维护者确认;(b) owner 书面批准 solo 期 bypass actor 并回填对应 manifest 的 `bypass_actors`。 - **D4**:管理员创建 `pypi`/`testpypi` Environment、绑定 trusted publisher、建立 `v*` tag rule,并提供变更前后 API 摘要。 - **D5-PVR**:管理员在 Settings → Security 开启 Private Vulnerability Reporting,`GET /private-vulnerability-reporting` 返回 `{"enabled":true}`。 diff --git a/docs/governance/evidence/m1-bootstrap-chain-20260823.md b/docs/governance/evidence/m1-bootstrap-chain-20260823.md new file mode 100644 index 00000000..0a9499f9 --- /dev/null +++ b/docs/governance/evidence/m1-bootstrap-chain-20260823.md @@ -0,0 +1,34 @@ +# M1 Bootstrap 链路证据(2026-08-23) + +> 执行人角色:管理员(@cloudQuant)。所有 SHA 均可经 `git log` / GitHub API 复核。 +> 对应计划:`docs/迭代计划/迭代03-开源项目治理与社区PR协作/正式迭代计划.md` M1 步骤 1–6。 + +## 分支创建与合并链 + +| 步骤 | 对象 | SHA / URL | 说明 | +|---|---|---|---| +| BOOTSTRAP_SHA 记录 | 远端 `master` | `1436ec0adaf4b283a54bfe69f5be163df3e3e3b9` | 决策日志 D0 已登记 | +| `dev` 创建 | `refs/heads/dev` | `1436ec0a`(= BOOTSTRAP_SHA) | M1 步骤 1;此时未切默认分支 | +| bootstrap 分支 | `governance/bootstrap` | `198f88a6` → `9bfe5f88` | 含 M0–M5 六个里程碑提交及演练修复 | +| Bootstrap PR | [#1](https://github.com/cloudQuant/bt_api_py/pull/1) | merge 于 2026-08-23T07:47:07Z | 合入后 `master` = `bcf6b77f` | +| 同步 PR master→dev | [#3](https://github.com/cloudQuant/bt_api_py/pull/3) | merge 于 2026-08-23T08:51:17Z | 合入后 `dev` = `f338199b` | +| 默认分支切换 | repo API PATCH | 切换前 `master` → 切换后 `dev` | 仅在同步 PR 通过后执行 | + +## 后续治理提交(dev 线) + +- PR #9 `fix(ci): correct gitlink detection…` → `dev` = `fbea4515` +- PR #11 `fix(ci): echo markdown fences…` → `dev` = `7f0b63a5` + +## 默认分支切换前后 API 摘要(脱敏) + +```text +GET /repos/cloudQuant/bt_api_py → default_branch + 切换前: "master" + 切换后: "dev" (PATCH /repos/cloudQuant/bt_api_py, field default_branch=dev) +``` + +## 结论 + +- fork 新建 PR 的默认目标分支为 `dev`(GitHub 行为由默认分支决定)。 +- `master` 自 bootstrap 起仅接收显式 PR 合并,无直接 push。 +- 本链路满足计划 §8 Implementation Complete 第 2 条的分支模型一致性要求。 diff --git a/docs/governance/evidence/m4-draft-pr-drills-20260823.md b/docs/governance/evidence/m4-draft-pr-drills-20260823.md new file mode 100644 index 00000000..8811d273 --- /dev/null +++ b/docs/governance/evidence/m4-draft-pr-drills-20260823.md @@ -0,0 +1,52 @@ +# M4 五类草稿 PR 演练证据(2026-08-23) + +> 执行人角色:管理员/triage(@cloudQuant)。观察期模式:`PR Governance` report-only。 +> 通过标准(计划 M4/M6):所有 required 候选 summary 在适用与不适用路径均稳定出现,无 `Waiting for status` 卡死。 + +## 演练矩阵 + +| 场景 | PR | base | 结果 | 关键观测 | +|---|---|---|---|---| +| D1 文档/R0 | [#5](https://github.com/cloudQuant/bt_api_py/pull/5) | `dev` | 关闭(已归档) | governance 输出 `OK: PR metadata satisfies the governance routing table.`;`deploy`/`submodule-matrix` 在不适用路径稳定 skipped | +| D2 R2 核心 | [#6](https://github.com/cloudQuant/bt_api_py/pull/6) | `dev` | 关闭(已归档) | 触及 `bt_api_py/bt_api.py`(仅 docstring);全检查通过 | +| D3 性能线 | [#7](https://github.com/cloudQuant/bt_api_py/pull/7) | `code-optimization` | 关闭(已归档) | check 名称齐全(build/deploy/Quality Gates 等);build 失败为该分线**预存问题**(numpy 构建元数据 + 22 个 strict 文档警告),与演练变更无关 | +| D4 hotfix→master | [#4](https://github.com/cloudQuant/bt_api_py/pull/4) | `master` | 关闭(已归档) | 两阶段验证见下 | +| D5 SHA bump | [#8](https://github.com/cloudQuant/bt_api_py/pull/8) / [#10](https://github.com/cloudQuant/bt_api_py/pull/10) | `dev` | 关闭(已归档) | 真实 gitlink 变更(bt_api_ctp a8a3792→8849421);两轮验证见下 | + +## D4 hotfix 双路径 + +- 第一阶段(无标签):governance 摘要正确列出违规 —— `exactly one risk: label is required, found none`、`missing labels: ['release:hotfix', 'risk:r3']`、`master PR lacks reproduction/regression/test evidence`。 +- 第二阶段(补 `risk:r3`+`release:hotfix`+证据正文后重触发):输出转为 `OK: PR metadata satisfies the governance routing table.`。 + +## D5 SHA bump 双路径 + +- 第一轮:Gate 报告 **not-applicable**——与事实不符,暴露检测缺陷(见下节缺陷 #4)。 +- 第二轮(PR #9 修复后):Gate 正确进入 **validated (1 gitlink change(s))** 路径并执行完整递归校验。 + +## 稳定出现的 check 名称清单 + +`PR Governance / Summary`、`Quality Gates`、`Tests / Quality Gate`、 +`Full Suite (Python 3.11, Ubuntu)`、`Compatibility / Compatibility (Python , )`、 +`Submodule Gate / Summary`、`build`;不适用路径:`deploy`、`submodule-matrix` 稳定 skipped。 +与 `.github/governance/required-checks.json` 登记一致(`Tests / Quality Gate` 为聚合 job 实名,无 drift)。 + +## 观察期发现并修复的缺陷(均经独立 PR 落地) + +| # | 缺陷 | 修复 | +|---|---|---| +| 1 | `pr-governance.yml` summary 步骤 Markdown 围栏被当裸命令执行(exit 127) | commit `96468674` | +| 2 | alpaca 插件集成测试路径错误且依赖本地检出 | commit `9423f6b2`(含缺失时 skip) | +| 3 | Quality Gate 历史债务首次暴露:ruff 627、格式化 44 文件、mypy 73;内含 F821 真实 bug(`_update_weights_based_on_performance` 的 `f1_score` 遮蔽,运行时必崩 TypeError);mixin stub 遮蔽回归 | PR [#2](https://github.com/cloudQuant/bt_api_py/pull/2) | +| 4 | gitlink 检测在两处同时失效:`awk '$4 ~ /160000/'` 测的是新 SHA 字段;Python 解析 `cols[2]=="160000"` 检查旧 SHA 且新旧索引错位 | PR [#9](https://github.com/cloudQuant/bt_api_py/pull/9) | +| 5 | `submodule-tests.yml` validated 分支第三个同类围栏 bug(exit 127) | PR [#11](https://github.com/cloudQuant/bt_api_py/pull/11) | + +## 记录在案、超出本迭代范围的发现 + +1. `code-optimization` 分线 docs build 预存失败(见 D3)。 +2. `install_and_test_all.py` 在 hosted runner 上 0/60 通过——缺原生构建依赖(如 CTP 所需 swig)。子模块完整校验的 CI 可用性需后续迭代处理。 +3. 本地全套件运行期间曾有并发会话改写 fixture 导致一次性误报(瞬态,复跑即消)。 + +## 严格模式启用 + +演练完成后:repo variable `PR_GOVERNANCE_STRICT=true`(2026-08-23T09:42:32Z 设置)。 +此后 governance 校验违规将硬失败;分支 Ruleset 仍未应用(见 m6 验收矩阵的 Ruleset 行)。 diff --git a/docs/governance/evidence/m6-acceptance-matrix-20260823.md b/docs/governance/evidence/m6-acceptance-matrix-20260823.md new file mode 100644 index 00000000..a224d00d --- /dev/null +++ b/docs/governance/evidence/m6-acceptance-matrix-20260823.md @@ -0,0 +1,51 @@ +# M6 正式验收矩阵(2026-08-23) + +> 执行人角色:管理员(@cloudQuant)。判定依据:计划 §M6 验收矩阵与 §8 完成定义。 +> 配套证据:`m1-bootstrap-chain-20260823.md`、`m4-draft-pr-drills-20260823.md`。 + +## 七维验收矩阵 + +| 维度 | 必须证据 | 状态 | 说明 | +|---|---|---|---| +| 分支模型 | D0 决策、bootstrap 链、默认分支 API | **通过** | `dev` 为默认入口(API 前后留证);bootstrap 后 `master` 仅接收显式 PR;链路 SHA 可串联(见 m1) | +| 所有权 | CODEOWNERS errors API | **通过** | `GET /codeowners/errors` → `{"errors":[]}`;CODEOWNERS 覆盖核心路径并已在 `master`/`dev` 生效 | +| Ruleset | API 摘要与 manifest diff | **一致·推迟应用** | 远端 `rulesets=[]` 与全部 manifest 的 `disabled+gated` 状态一致;`verify_github_governance.py` exit 0。激活推迟理由见下节 | +| CI | 五类草稿 PR 演练 | **通过** | 所有候选 summary 在适用/不适用路径稳定出现(见 m4 清单);无 `Waiting for status` 卡死;strict 模式已启用 | +| 安全 | SECURITY.md、gitleaks 记录 | **部分通过** | 增量 gitleaks 生效(浅克隆缺陷已修);bandit B105 跳过附书面理由;仓库内无秘密。PVR 未启用(外部动作) | +| 发布 | TestPyPI record、Environment/tag 证据 | **阻塞·外部授权** | workflow 侧守卫已落地(manual 仅 testpypi+expected_sha;release 校验 tag/版本/可达性);TestPyPI 演练待发布负责人单独授权(D4) | +| 子模块 | pilot bump PR 双端证据 | **机制通过** | 插件仓提交在远端 + 主仓 gitlink bump PR 全链路演练;完整校验 runner 的 0/60 环境失败已记录为后续迭代事项 | + +## Ruleset 推迟应用的理由(重要) + +四个 manifest 均为 `disabled` 且带门控标记,远端未创建任何 Ruleset——**这是有意的合规状态**: + +1. `master.json`:pending D3(双人审批无第二维护者)。 +2. `dev.json` / `code-optimization.json`:检测逻辑经演练修复后具备激活条件,但存在**单一维护者运营约束**——Ruleset 要求非作者批准时,唯一维护者无法批准自己的 PR,激活即冻结所有合并。解除需二选一:(a) 第二维护者获得 write 权限并完成 review drill;(b) owner 明确批准 bypass actor 策略并回填 manifest 的 `bypass_actors`。 +3. `release-tags.json`:pending D4(bypass_actors 待填入确认的 release actor ID)。 + +依据 evidence/README 规则第 3 条:远端状态与 manifest `enforcement` 字段必须在同一治理提交中同步翻转——上述门控未解除前,任何单侧激活都构成 drift。 + +## 观察期强化(已生效) + +`PR_GOVERNANCE_STRICT=true`(2026-08-23T09:42:32Z):governance 校验违规从此硬失败。 +该变量不依赖 Ruleset,即可对全部 PR 强制执行路由表与标签纪律。 + +## 管理员交接包(Blocked 解除清单) + +| 门 | 待办动作 | 责任人 | +|---|---|---| +| D3-master / 运营约束 | 确认第二维护者(write 权限 + 在 CODEOWNERS 生效分支完成一次 review drill);或决策 solo 期 bypass actor 并更新 manifest | 管理员 + 核心维护者 | +| D4 | 创建 `pypi`/`testpypi` Environment;在 PyPI 侧绑定 trusted publisher;回填 release-tags actor;随后按 `docs/governance/release-flow.md` 执行 TestPyPI 演练 | 管理员 + 发布负责人 | +| D5-PVR | Settings → Security 开启 Private Vulnerability Reporting,API 返回 `{"enabled":true}` 后更新决策日志 | 管理员 | +| Ruleset 激活顺序 | 门控解除后:同一治理提交内翻转 manifest `enforcement` → 合入 → 应用远端 → 重跑 verify 脚本 | 管理员 | +| M7 | 以本目录为起点开始周度量;连续 4 周满足稳定化退出条件后方可宣称流程持续运行 | triage 轮值 | + +## 完成定义对照(计划 §8) + +1. M0–M5 全部通过;M6 执行至当前权限与门控可及范围,所有假设均已声明(无隐式默认值)。✅ +2. `dev` 默认入口、`master` 发布线、`code-optimization` 选择性 promotion 在文档、workflow、manifest 与草稿 PR 中一致。✅ +3. CODEOWNERS、manifest 与远端比对(exit 0)、稳定 CI summaries、SECURITY 入口、Issue/PR 模板、子模块 PR 路径均有证据。✅ +4. TestPyPI 路径已准备但**未演练**——按计划要求显式标记为下一 release 的外部验收门,未伪造发布证据。✅ +5. 未将离线/模拟结果描述为实盘或生产安全保证。✅ + +**判定:Implementation Complete(含显式声明的推迟项与外部验收门);Operationally Proven 待 M7 四周观察期后另行宣称。**