45 lines
5.5 KiB
Markdown
45 lines
5.5 KiB
Markdown
# 通用规范采纳记录
|
||
|
||
- 项目/负责人：Logging-System / weichen
|
||
- 状态：active
|
||
- 规范位置：`deps/development-guidelines`
|
||
- 规范性文档目录：`policy/`（项目规则与制度放此处）
|
||
- 过程文档位置：`.task/`（任务卡与交付流程证据，随 PR 维护）；`docs/records/`（其他过程记录，项目内固定目录豁免，方案与验证记录）；任务主记录在 Gitea PR
|
||
- 版本权威：本仓 gitlink `deps/development-guidelines` @ `2688fd2be6a5`（完整 SHA `2688fd2be6a52c0bf110e7e6366b6f291ab5e4eb`，内容版本 `0.1.0-draft.12`）；无可读发布标签；治理工具 gitlink `deps/development-manager` @ `bd3a7de57a3a`（完整 SHA `bd3a7de57a3a9e1a4495b94c5fa5c08d71e7be8c`）
|
||
- 批准/生效依据：`feature/governance-adoption PR（Logging-System）`；合入前须在 `.task/feature-governance-adoption.md` 记录正负例、Review 与 CI 结果
|
||
- 替代范围和迁移说明：本次把 Guidelines gitlink 从 `26b562d2e34f`（`0.1.0-draft.6`）升级到 `2688fd2be6a5`，并接入共享治理套件（`scripts/dm`、`scripts/agent-exec`、`scripts/task`、`scripts/hooks/pre-commit`、`.gitea/workflows/governance.yml`）。无旧 Agent 执行器需要替代。`.gitea/workflows/ci.yml` 两个 job 原有的 `uses: actions/checkout@v4` 步骤已替换为自包含内联检出，因为 runner 无法访问 github.com；run 步骤未改变。
|
||
|
||
| 规范/工作流 | 适用条件与范围 | 采纳或不适用理由 | 执行方式/证据 |
|
||
|---|---|---|---|
|
||
| core/baseline.md | 日常工作 | 日志是失败定位的另一半 | manual |
|
||
| workflows/delivery.md、debugging.md、handoff.md | 交付、排障与交接 | 排障会直接使用本库 | manual |
|
||
| standards/collaboration.md | 合入前同步目标分支；消费方固定版本 | 本仓不跟随消费方分支；PR 前后同步并记录 | manual |
|
||
| standards/merge-queue.md | 多个就绪任务的最终同步、CI、Review 与合入调度 | 不适用：单人顺序合入，不存在多个并行就绪候选 | 不适用 |
|
||
| standards/verification.md | 并发、脱敏、排空、模块接口 | `go vet` 与 `go test`，见 PROJECT.md「验证命令」；CI `ci.yml` 执行 vet 与 test | manual + CI |
|
||
| standards/observability.md | trace、级别、重放 | 本仓实现日志半边 | manual |
|
||
| standards/configuration.md | 文件、环境变量、出口 | `config.Load` / `LOGSYS_*` | manual |
|
||
| standards/security.md | 脱敏与采集 token | 写前与入库前各脱敏一次 | manual |
|
||
| standards/failure-containment.md | 队列满时的丢弃与阻塞策略 | 队列满丢弃最新一条，不阻塞业务 goroutine | manual |
|
||
| standards/module-contracts.md | 公开接口与依赖边界 | 不导入错误码库；鸭子接口是稳定边界 | manual |
|
||
| standards/documentation.md | 三层文档 | `docs/` 与 `docs/records/` 分开；任务过程记录按 `.task/` 与 PR | manual |
|
||
| standards/multi-repo.md | 被 submodule 消费；示例模块用相对 replace | 主模块不嵌套错误码库 | manual |
|
||
| standards/data-reliability.md | JSONL 采集文件 | 无事务数据库；文件是日志投影 | manual |
|
||
| standards/agent-execution.md | 工程 Agent 执行（实施、修复、测试、审阅） | 配置见 AGENT-EXECUTION.md；入口 `scripts/agent-exec`（validate / admit）；CI `governance` 工作流运行 validate 与 governance check；本地 admit 待 host 启用 `core.hooksPath` 后生效 | advisory（CI；分支保护尚未设为必需检查，设为必需检查并有阻断负例后再登记 enforced）+ advisory（本地）；证据：`governance check + 正负例（.task/feature-governance-adoption.md）` |
|
||
| standards/testability.md、workflows/design-verification.md | 功能增量的设计与可测试性 | 跨包变更按增量写明验收与测试范围 | manual |
|
||
| standards/release-operations.md | 无制品流水线 | 消费方固定 gitlink | 不适用 |
|
||
| workflows/automation.md | 无独立定时任务 | 异步批导出是库行为，不是运营自动化 | 不适用 |
|
||
|
||
## 项目差异
|
||
|
||
| 原规则/章节 | 项目采用方式 | 原因与风险 | 负责人/复查条件 |
|
||
|---|---|---|---|
|
||
| documentation.md 过程仓默认独立仓库 | `docs/records/` 豁免 | 个人项目。风险同其他三仓 | 采集服务对外长期运行时复查 |
|
||
| documentation.md 过程仓默认独立仓库 | `.task/` 仓内任务卡与交付证据目录 | 个人项目，任务卡随 PR 维护。风险同其他三仓 | 采集服务对外长期运行时复查 |
|
||
|
||
## 本次升级或首次接入验证
|
||
|
||
- 子模块固定：`deps/development-guidelines` @ `2688fd2be6a52c0bf110e7e6366b6f291ab5e4eb`；`deps/development-manager` @ `bd3a7de57a3a9e1a4495b94c5fa5c08d71e7be8c`。
|
||
- `examples/trace` 仍使用自己的 `go.mod` replace，不改为依赖 `deps/` 下的错误码副本。
|
||
- 入口与门禁：`AGENTS.md`「Agent 执行与新项目准入（强制）」、`AGENT-EXECUTION.md`（候选 `cursor-agent-stable`）、`.gitea/workflows/governance.yml`；正负例与结果记录在 `.task/feature-governance-adoption.md`。
|
||
- 回退：通过普通 PR 恢复 `deps/development-guidelines` 上一 gitlink（`26b562d2e34f`）及其 `.gitmodules` 条目，移除 `deps/development-manager` gitlink 及其 `.gitmodules` 条目，并移除治理入口（`scripts/dm`、`scripts/agent-exec`、`scripts/task`、`scripts/hooks/pre-commit`、`.gitea/workflows/governance.yml`、`.task/templates/task-card.md`、`AGENT-EXECUTION.md`），还原 AGENTS.md / PROJECT.md 中追加的治理章节，并将 `.gitea/workflows/ci.yml` 两个 job 的检出步骤恢复为 `uses: actions/checkout@v4`。
|