docs: document direct push path for docs changes

This commit is contained in:
Codex
2026-05-28 10:39:33 +08:00
parent 1d0f690dc4
commit 912d6251a1
3 changed files with 11 additions and 7 deletions
+3 -3
View File
@@ -37,7 +37,7 @@ HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥
- Runner 和指挥常用工作区是 `/workspace/hwlab`;进入仓库先检查分支与工作树状态,详见 [docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)。
- G14 CI/CD 由 `G14` source branch、G14 k3s Tekton 和 `G14-gitops` branch 驱动;需要构建、Playwright、check、发布预检或运行面验证时放到 G14 k3s/runner/CI/CD,不在 master server 跑重型验证。
- D601 发布/构建 worktree 纪律只适用于 legacy 路径回溯,不再作为当前 HWLAB 发布默认入口;当前入口见 [docs/reference/g14-gitops-cicd.md](docs/reference/g14-gitops-cicd.md)。
- 当前一律走 PR 工作流;不要直推 `main`,默认不要合并自己的 PR;用户或指挥官明确授权且满足门禁时可按长期参考自合并,不要改 PROD、不要重启服务。
- 交付路径按变更风险选择:单纯文档、CLI/helper 轻量变更直接提交并 push 到 `origin/G14`,不开 PR;业务代码、运行面、发布链路、Secret、权限、数据迁移、PROD 或其他高风险变更走 PR 工作流;不要直推 `main`,默认不要合并自己的 PR;用户或指挥官明确授权且满足门禁时可按长期参考自合并,不要改 PROD、不要重启服务。
- `DC-DCSN-P0-2026-003` / [pikasTech/HWLAB#78](https://github.com/pikasTech/HWLAB/issues/78) 是当前 M3 虚拟硬件可信闭环的上位约束;其他任务不得把 SOURCE、LOCAL、DRY-RUN、fixture 或前端状态误报为 M3 DEV-LIVE。
- 仓库禁止创建或提交 repo report 目录;验收、进展和结论只承载在 #7、专题 issue、每日简报或 PR/issue 评论。临时 JSON 只能写入 `/tmp``.state` 或 CI artifact,不能进入源码仓库。
@@ -56,7 +56,7 @@ HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥
- 文档治理与 docs-spec 本地权威:[docs/reference/documentation-governance.md](docs/reference/documentation-governance.md)
- 架构和 M3 主线:[docs/reference/architecture.md](docs/reference/architecture.md)
- DEV 运行态、端口、k3s 和 DB DNS 边界:[docs/reference/dev-runtime-boundary.md](docs/reference/dev-runtime-boundary.md)
- G14 GitOps 发布、SecretRef preflight、runner/host 边界镜像发布:[docs/reference/g14-gitops-cicd.md](docs/reference/g14-gitops-cicd.md)
- G14 GitOps 发布、SecretRef preflight、runner/host 边界镜像发布和单纯文档/CLI 直推规则[docs/reference/g14-gitops-cicd.md](docs/reference/g14-gitops-cicd.md)、[docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)
- G14 GitOps CI/CD、Tekton/Argo CD、集群内 registry 和无锁镜像化发布:[docs/reference/g14-gitops-cicd.md](docs/reference/g14-gitops-cicd.md)
- G14 CI/CD 性能基线、根因分析和加速收益估算:[docs/reference/g14-cicd-performance.md](docs/reference/g14-cicd-performance.md)
- Code Agent 对话就绪与真实回复判定:[docs/reference/code-agent-chat-readiness.md](docs/reference/code-agent-chat-readiness.md)
@@ -73,7 +73,7 @@ HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥
- 中文优先:issue、PR 正文、长期参考文档和用户可见说明默认用中文;英文术语只在命令、协议、接口、ID、路径和标准名需要保真时保留,详见 [docs/reference/chinese-first-documentation.md](docs/reference/chinese-first-documentation.md)。
- 用户反馈优先:用户和参谋提出的问题默认按高优先级用户反馈处理,blocker 状态不能替代反馈分流,必须挂到 [pikasTech/HWLAB#7](https://github.com/pikasTech/HWLAB/issues/7) 醒目位置,详见 [docs/reference/user-feedback-triage.md](docs/reference/user-feedback-triage.md)。
- docs-spec 本地权威优先:涉及 `AGENTS.md``docs/reference/*.md` 或过程文档蒸馏时,先按 [docs/reference/documentation-governance.md](docs/reference/documentation-governance.md) 执行,不另建同级规则副本。
- PR 工作流优先:从最新 `origin/main` 创建短分支,提交 PR 到 `pikasTech/HWLAB:main`runner 不直推 `main`,默认不自合并;显式授权且满足门禁时按协作规则收口,不改 PROD、不重启服务,详见 [docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)。
- 交付路径按风险选择:单纯文档、CLI/helper 轻量变更直接提交并 push 到 `origin/G14`,不开 PR;业务代码、运行面、发布链路、Secret、权限、数据迁移、PROD 或其他高风险变更走 PR 工作流,详见 [docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)。
## 常用轻量命令
+6 -2
View File
@@ -21,13 +21,17 @@
- D601 发布和 rollout 工作区是 `/home/ubuntu/workspace/hwlab`
- 不要清理、reset 或复用无关 runner worktree 作为发布真相。
## 分支和 PR 工作流
## 分支和交付工作流
- 单纯文档、CLI/helper 轻量变更默认直接提交并 push 到 `origin/G14`,不开 PR;这类变更仍要先从最新 `origin/G14` 创建独立 worktree,提交前审查 diff,只提交当前任务相关文件。
- 业务代码、运行面、发布链路、Secret、权限、数据迁移、PROD、重启服务、CI/CD 控制面高风险变更或其他影响 runtime truth 的变更默认走 PR 工作流。
- 用户或指挥官给出最新交付纠偏时,以最新要求为准,删除旧断言或旧门禁,不用 feature flag、legacy mode 或双路径长期并存绕开最新要求。
- 从最新 `origin/main` 创建短分支。
- 不要直推 `main`
- 不要修改 PROD。
- 除非任务明确授权,不要重启服务。
-`pikasTech/HWLAB:main` 创建 PR。
- 需要 PR 时`pikasTech/HWLAB:main` 创建 PR。
- runner 默认不合并自己的 PR;用户或指挥官可以对单个 PR 明确授权 runner 自合并。
- 自合并前必须同时满足:PR 为 `MERGEABLE/CLEAN` 或等价无冲突状态;required checks 没有失败;D601/CI 或指定运行态验证证据已贴到 PR/issue;变更不涉及 PROD、Secret、权限提升、数据迁移或未授权重启;runner 在最终评论中列出提交 SHA、验证命令和回滚边界。
- 当前 GitHub 写入仍优先走 UniDesk CLI 或 repo-owned GitHub 路径;若当前 CLI 不支持 merge,必须使用可审计的授权路径,不能用无记录的本地绕行来规避审计。
+2 -2
View File
@@ -49,7 +49,7 @@ G14 CI/CD 耗时必须按阶段测量,不能只看一个 PipelineRun 总时长
| `single-component-build` | 3.2-5.5m | 4-7.5m |
| `full-rebuild` | 6-7m | 6.5-9m |
这些值是性能基线,不是发布 SLO。任何 CI/CD 优化 PR 都应按同一种运行类型做 before/after 对比。
这些值是性能基线,不是发布 SLO。任何 CI/CD 优化变更都应按同一种运行类型做 before/after 对比。
## 根本原因
@@ -146,7 +146,7 @@ retention cleaner 会删除超过保留窗口的 completed PipelineRuns,但近
## 验收标准
任何优化 PR 只有在给出同运行类型 before/after 数据,并保持以下不变量时,才算可合并
任何优化变更只有在给出同运行类型 before/after 数据,并保持以下不变量时,才算可交付
- Source commit 仍是唯一 artifact identity。
- 镜像仍使用 commit tag 和 digest 作为发布身份。