3.2 KiB

Raw Blame History

贡献指南

本仓库采用短生命周期分支加 Pull Request（PR）的协作方式。当前处于 0–1 阶段，合并门禁以可重复构建、已有自动化测试与人工代码审查为准；没有验收环境时，禁止把“已验收”写入 PR。

开始前

从受保护的 main 创建个人任务分支；在完成 master 到 main 的迁移前，暂以受保护的 master 作为唯一主干。
先在本地 Markdown issue tracker 创建或领取任务：.scratch/<feature>/issues/<NN>-<slug>.md。
在任务中写明目标、验收条件、计划修改文件、影响模块、依赖与阻塞项。
同一时间一个文件只能有一个写入责任人。根 pom.xml、crm-base、crm-auth、部署文件、公共 DTO、数据库结构变更均属于高冲突区，开始前必须与对应 owner 对齐。

分支与提交

功能：feature/<ticket>-<short-name>
缺陷：fix/<ticket>-<short-name>
紧急修复：hotfix/<ticket>-<short-name>
分支只服务一个任务，建议在 1–3 天内完成并合并；禁止长期个人分支和多人共享同一任务分支。
提交只表达一个可理解的目的。格式化、重构与业务功能不得混在同一提交。
每次发起 PR 前，先同步主干并解决冲突。团队统一采用 rebase 时，须在自己的分支上完成，绝不改写主干历史。

本地质量检查

使用 JDK 17 与 Maven 3.9+。CI 使用下列同等命令：

mvn -B -s settings.xml verify

修改 Java 文件后，还必须确认没有 UTF-8 BOM。PowerShell 示例：

Get-ChildItem -Recurse -Filter *.java | ForEach-Object {
  $bytes = [IO.File]::ReadAllBytes($_.FullName)
  if ($bytes.Length -ge 3 -and $bytes[0] -eq 0xEF -and $bytes[1] -eq 0xBB -and $bytes[2] -eq 0xBF) {
    throw "UTF-8 BOM: $($_.FullName)"
  }
}

当前没有自动化验收环境。涉及 API、数据库、权限、异步任务或部署的改动，PR 必须明确写出人工验证步骤、执行人和结果；无法验证时标记为阻塞，而不是猜测通过。

Pull Request 要求

关联本地任务文件路径，并说明实现范围和不在本次范围内的内容。
填写测试命令及实际结果；CI 失败不得合并。
说明 API、配置、数据结构、权限、部署和回滚影响；没有影响时明确写“无”。
至少一名非作者 reviewer 批准。高冲突区还需要对应模块 owner 批准。
默认使用 squash merge；合并后删除远端任务分支。

人工与 Agent 的共同规则

Agent 只能在已领取的任务范围和独立 worktree 中工作，不能直接推送主干、合并 PR 或绕过保护规则。
使用 Agent 前先记录计划修改文件；发现文件重叠，先拆分任务或指定一个人负责公共 seam。
Agent 生成的代码、文档和命令由提交 PR 的人承担审查与安全责任。
不向 Agent、CI 或日志提交生产凭据、管理员 token、私钥或真实客户数据。

0–1 阶段的升级条件

当具备独立集成环境和稳定验收样例后，新增集成测试、部署验证和发布 tag 检查；形成固定发布节奏后才启用 release/<version> 分支。

3.2 KiB Raw Blame History