You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
59 lines
3.2 KiB
59 lines
3.2 KiB
2 days ago
|
# 贡献指南
|
||
|
|
|
||
|
|
本仓库采用短生命周期分支加 Pull Request（PR）的协作方式。当前处于 0–1 阶段，合并门禁以可重复构建、已有自动化测试与人工代码审查为准；没有验收环境时，禁止把“已验收”写入 PR。
|
||
|
|
|
||
|
|
## 开始前
|
||
|
|
|
||
|
|
1. 从受保护的 `main` 创建个人任务分支；在完成 `master` 到 `main` 的迁移前，暂以受保护的 `master` 作为唯一主干。
|
||
|
|
2. 先在本地 Markdown issue tracker 创建或领取任务：`.scratch/<feature>/issues/<NN>-<slug>.md`。
|
||
|
|
3. 在任务中写明目标、验收条件、计划修改文件、影响模块、依赖与阻塞项。
|
||
|
|
4. 同一时间一个文件只能有一个写入责任人。根 `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 使用下列同等命令：
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
mvn -B -s settings.xml verify
|
||
|
|
```
|
||
|
|
|
||
|
|
修改 Java 文件后，还必须确认没有 UTF-8 BOM。PowerShell 示例：
|
||
|
|
|
||
|
|
```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>` 分支。
|