git 仓库维护方案标准

本方案定义 lab-edu 四仓库的 git 维护标准：仓库命名、分支、提交、MR、版本、CI、敏感信息与回滚。 上位约束：宪法 §2（分层）/ §4（框架优先）/ §7（变更与评审）；细则唯一权威 CONTRIBUTING 的既定约定。README/PR 模板等工程细则不在此重复（DRY）。

1. 仓库与命名

  • 四个独立 GitLab 仓库，均置于 lab-edu group：docs / core / web / infra。
  • 命名遵守 CONTRIBUTING 模块/仓库命名规则（小写 + 短横线，无私有缩写）。

2. 分支模型（Trunk-based 简化）

  • main 为唯一常驻分支；一切变更经 Merge Request（MR）合入，禁止直接 push main。MVP 期单人也不例外——保留审计轨迹，且 MR 是宪法 §7 评审的落地入口。
  • 分支名：feat/<slug> | fix/<slug> | docs/<slug> | refactor/<slug> | chore/<slug>。
  • 一个分支与 MR 对应一个可独立验证的逻辑交付，可以包含该交付所需的多条 task；MR 描述逐项关联任务编号，任务仍按 CONTRIBUTING 的文件粒度拆分和逐条验证。完成即合入，不留长期分支。

3. 提交信息

  • Conventional Commits：<type>(<scope>): <subject>；type ∈ feat / fix / docs / refactor / chore / test / ci。
  • subject 用中文，≤50 字符，结尾无标点（宪法 §5 文档语言条款）。
  • 涉及 Spec/Plan/Tasks 的提交，subject 末尾附引用 id（如 [T003]、[auth-spec-001]），保证提交可溯源到规格。

4. MR 规范

  • MR 标题 = 分支对应提交的 subject。
  • MR 描述三段式：
  • 依据：关联的 spec/plan id（无则写"无，直改"——MVP 期小改动可省规格，按执行摘要的取舍原则）；
  • 改动：简述，限 1 个逻辑单元；
  • 宪法符合性自查：框架优先（§4）/ 范围红线（§8）/ 质量底线（§5）三项勾选 + 需联动文档路径。
  • 一个 MR ≤1 个逻辑单元；大改动按 tasks.md 拆多个 MR。
  • 评审：总架构师初审 → 产品经理终审（与宪法评审一致，MVP 期可由产品经理一人代行并在 MR 留言留痕）。
  • 合并方式：feature 分支 rebase 于最新 main 后快速合并，保持线性历史；禁止 force-push main。

5. 版本与 tag

  • MVP 期四仓库不打 git tag；版本唯一权威：文档类在文件 frontmatter（SemVer），代码类小版本在构建配置（pom.xml / package.json），宪法只维护基线（宪法 §3）。
  • core 首次生产部署时打 v0.1.0，此后按 SemVer 递增；发布流程细则随 infra 相关 Spec。

6. CI（随各仓库首个提交上线，MVP 最小集）

仓库 MVP 最小 CI 失败处理
docs mkdocs build + GitLab Pages 发布 MR 阻塞
core mvn verify（编译 + 单测） MR 阻塞
web npm ci + lint + build MR 阻塞
infra docker compose config 校验 MR 阻塞
  • CI 配置属各仓库代码；runner 规格、缓存等细则归 infra 规划，不在此展开（YAGNI）。

7. 敏感信息

  • .env* 与密钥文件一律不入库；密钥走 GitLab CI/CD variables（masked）。
  • 残留密钥：发现即轮换 + 提交历史审计（含历史提交内容，必要时重写仅限未共享分支）。

8. 回滚与历史

  • 回滚用 git revert 生成反向提交；不改写已推送 main 的历史。
  • 破坏性变更（DB migration / 接口破坏）上线前评审并留备份方案，细则归对应核心 Spec。

9. 初始化执行

  • 本方案已于 2026-10-29 随整稿批准；取得 GitLab 实例、group 和访问条件后执行：四仓库 git init + main 保护 + 分支模型落地；仓库创建与 CI 配置（§6）随各仓库首个代码提交一并上线。

三原则审查（提交前）

  • KISS：MVP 最小集——无 CodeOwners、无 release plugin、无 monorepo tooling、无 tag 流程（首发再说）。
  • YAGNI：单人多仓库 MVP 期省掉：分阶段部署分支、backport、changelog 自动化、依赖机器人；全部挂靠失败可等首个真实需求。
  • DRY：不重复 CONTRIBUTING 已定约定（命名/提交格式仅按既有约定引用）；规范细则留 CONTRIBUTING，本方案专注 git 层面。

评审记录

用户于 2026-10-29 确认整稿评审包，包含多 task 组成一个逻辑 MR 的修订。四仓库远端尚未创建或配置保护；本文件批准不等于已执行。依据见批准记录（本地资料，未发布）。

[SPEC-KIT APPENDED 2026-10-30] main 分支规则执行记录

四个新建私有项目均已创建 main 分支规则：无人可直推、维护者可经 MR 合并、禁止强制推送。远端仍为空，首次 main 引导和 CI 随首批逻辑 MR 落地；不得以初始化为由绕过 MR 规则。详见 仓库规划。

[SPEC-KIT APPENDED 2026-10-29] 用户命名修订

用户明确要求仓库直接命名 docs、core、web、infra，完整路径为 lab-edu/docs 等，不重复 group 前缀。本次将命名条款与 CI 表同步至 0.1.1；不修改仓库职责、分支流程和旧仓库禁读边界。远端实际创建状态见 repository-plan 与执行记录。