123 lines
5.9 KiB
Markdown
123 lines
5.9 KiB
Markdown
# 业务分支 Git 处理方案
|
||
|
||
本文档定义在本仓库进行业务开发时的分支模型、日常协作流程、合并策略、冲突处理与发布规范，并给出从 `main-framework` 分支合并到当前分支的标准步骤与命令示例。
|
||
|
||
## 分支模型
|
||
- `main-framework`：框架主线分支，承载通用框架能力与底层升级。
|
||
- `develop`：集成分支（如有），用于聚合多业务分支进行联调。
|
||
- `feature/*`：业务开发分支，以功能或需求编号命名，例如 `feature/order-approval`。
|
||
- `hotfix/*`：线上紧急修复分支，例如 `hotfix/login-captcha-null`。
|
||
|
||
命名建议：
|
||
- 使用全小写、连字符分隔；避免中文和空格；包含简短语义或任务号。
|
||
|
||
## 工作流程（日常循环）
|
||
1. 从远端更新框架主线：`git fetch origin && git checkout main-framework && git pull`。
|
||
2. 基于业务分支开展开发：`git checkout feature/xxx`。
|
||
3. 频繁从 `main-framework` 变更合并（或重置基线），保持同步：
|
||
- 合并：`git checkout feature/xxx && git merge main-framework`。
|
||
- 或重置基线（更干净的线性历史，需团队共识）：`git rebase main-framework`。
|
||
4. 提交与推送：按提交规范进行小步提交，`git push -u origin feature/xxx`。
|
||
5. 发起合入评审：对 `feature/xxx` → 目标分支（`develop` 或 `main-framework`）创建 PR，并通过 CI。
|
||
|
||
## 合并策略
|
||
- 默认使用 `merge --no-ff` 保留合并信息，便于回溯父子关系。
|
||
- 团队同意时，可在业务分支内使用 `rebase` 以获得线性历史；但对共享分支避免对已推送历史进行 rebase。
|
||
|
||
## 提交规范
|
||
- 提交信息格式：`<type>(scope): <subject>`
|
||
- `type`：feat / fix / refactor / docs / test / chore / perf / build / ci
|
||
- `scope`：可选，模块或子系统，如 `auth`、`quartz`
|
||
- `subject`：一句话描述改动，使用祈使句，如 `add captcha ttl config`
|
||
- 示例：`fix(quartz): handle null cron when loading jobs`
|
||
- 单次提交尽量关注一个变更点；避免将大量无关改动揉在一起。
|
||
|
||
## 冲突处理
|
||
1. 运行合并命令后，如提示冲突：
|
||
- 逐文件解决：打开冲突标记 `<<<<<<<`, `=======`, `>>>>>>>`，保留正确逻辑。
|
||
- 标记已解决：`git add <file>`。
|
||
2. 完成后继续：
|
||
- 合并：`git commit`（若自动生成合并提交信息可直接保存）。
|
||
- 变基：`git rebase --continue`。
|
||
3. 如需放弃变基过程：`git rebase --abort`；如需放弃合并：`git merge --abort`。
|
||
|
||
## 质量保障
|
||
- 合并后本地构建：`mvn -q -DskipTests spring-boot:run` 或 `mvn -q clean package`。
|
||
- 若包含前端：在 `framework/frontend` 下执行 `pnpm install && pnpm build`。
|
||
- 通过单元测试与基本功能自检后再推送远端。
|
||
|
||
## 常用命令速查
|
||
- 更新远端引用：`git fetch --all --prune`
|
||
- 查看当前分支：`git rev-parse --abbrev-ref HEAD`
|
||
- 查看变更：`git status -s`
|
||
- 暂存现场：`git stash push -u -m "auto-stash before merge"`，恢复：`git stash pop`
|
||
- 创建并推送分支：`git checkout -b feature/xxx && git push -u origin feature/xxx`
|
||
|
||
## 从 main-framework 合并到当前分支（标准步骤）
|
||
在仓库根目录执行：
|
||
|
||
1. 确认当前分支：
|
||
```sh
|
||
git rev-parse --abbrev-ref HEAD
|
||
```
|
||
2. 确保工作区干净（如有未提交改动，可先提交或使用 stash）：
|
||
```sh
|
||
git status --porcelain
|
||
```
|
||
3. 更新远端：
|
||
```sh
|
||
git fetch --all --prune
|
||
```
|
||
4. 若本地没有 `main-framework`，拉取远端追踪分支：
|
||
```sh
|
||
git branch --track main-framework origin/main-framework 2>/dev/null || true
|
||
```
|
||
5. 在当前分支执行合并：
|
||
```sh
|
||
git merge --no-ff main-framework
|
||
```
|
||
6. 解决冲突并提交（如有），然后本地验证构建与运行。
|
||
7. 推送当前分支：
|
||
```sh
|
||
git push
|
||
```
|
||
|
||
## 常见问题
|
||
- 找不到 `main-framework`：确认远端存在 `origin/main-framework`；如远端名非 `origin`，替换为实际远端名。
|
||
- 工作区脏导致合并失败：先提交或使用 `git stash` 暂存，再合并，结束后 `stash pop` 并解决可能冲突。
|
||
- 合并后启动失败：优先检查 `pom.xml`、`application-*.yml` 的配置合入及数据库变更迁移是否完整。
|
||
|
||
---
|
||
如需自动化执行“从 main-framework 合并到当前分支”，请确保工作区干净并已配置远端，然后按上文标准步骤执行即可。
|
||
|
||
## 自动化合并脚本
|
||
- 脚本位置：`D:\JavaProjectSpace\scripts\merge-main-framework.ps1`
|
||
- 作用：自动执行从 `origin/main-framework` 合并到当前分支的流程，包含工作区检查、自动暂存（可选）、`fetch`、合并、冲突策略与推送。
|
||
|
||
参数说明：
|
||
- `-RepoPath`：仓库路径，默认为脚本所在目录的上一级。
|
||
- `-AutoStash`：当工作区不干净时自动执行 `git stash push -u`，默认 `true`。
|
||
- `-Push`：合并成功后是否推送到远端，默认 `true`。
|
||
- `-OnConflict`：冲突策略，`abort` 立即中止并恢复现场，`leave` 保留冲突现场供手动解决，默认 `leave`。
|
||
|
||
使用示例：
|
||
```powershell
|
||
# 常用：自动暂存 + 推送，冲突保留现场
|
||
& "D:\JavaProjectSpace\scripts\merge-main-framework.ps1" -AutoStash $true -Push $true -OnConflict 'leave'
|
||
|
||
# 冲突直接中止合并（不会生成合并提交）
|
||
& "D:\JavaProjectSpace\scripts\merge-main-framework.ps1" -OnConflict 'abort'
|
||
|
||
# 禁止自动暂存，需确保工作区干净
|
||
& "D:\JavaProjectSpace\scripts\merge-main-framework.ps1" -AutoStash $false
|
||
```
|
||
|
||
退出码约定：
|
||
- `0`：合并（及推送）成功。
|
||
- `2`：存在冲突且策略为 `leave`，保留现场供手动解决（按提示执行 `git add` / `git commit`）。
|
||
- `1`：命令执行错误或远端分支不存在等异常。
|
||
|
||
注意事项：
|
||
- 需本机安装并可用 `git` 命令。
|
||
- 远端分支固定为 `origin/main-framework`，如远端名不同请调整脚本或配置。
|
||
- 合并完成后建议在后端与前端分别执行构建验证，确保配置与依赖同步。 |