160 lines
5.5 KiB
Markdown
160 lines
5.5 KiB
Markdown
# develop-framework 分支 Git 操作指南（面向 main-framework 主分支）
|
||
|
||
> 适用范围：`D:/JavaProjectSpace/framework` 项目（Spring Boot 3.3.x，可执行 JAR），远程仓库：`http://121.37.111.42:3000/ThbTech/JavaProjectRepo.git`
|
||
> 主分支：`main-framework`；开发分支：`develop-framework`
|
||
|
||
## 分支策略与目标
|
||
- `main-framework`：稳定发布分支，受保护（建议启用 PR 合并、代码审查、CI 通过）。
|
||
- `develop-framework`：日常开发分支，合并至主分支前需完成构建与自测。
|
||
- 推荐临时特性分支：`feature/<name>` 从 `develop-framework` 拉出，完成后合并回 `develop-framework`。
|
||
|
||
## 初始仓库设置
|
||
- 设置用户信息（确保提交署名一致）：
|
||
```
|
||
git config user.name "zhengsl"
|
||
git config user.email "zhengsl@163.com"
|
||
```
|
||
- 关联远程（如已有请忽略）：
|
||
```
|
||
git remote set-url origin http://121.37.111.42:3000/ThbTech/JavaProjectRepo.git
|
||
```
|
||
- 拉取远程分支列表并跟踪：
|
||
```
|
||
git fetch --all --prune
|
||
```
|
||
|
||
## 开发日常流程（在 develop-framework）
|
||
- 切换到开发分支并更新：
|
||
```
|
||
git checkout develop-framework
|
||
git pull --ff-only
|
||
```
|
||
- 提交更改（遵循约定式提交，示例）：
|
||
```
|
||
git add .
|
||
git commit -m "feat: 支持可执行JAR打包并优化资源复制逻辑"
|
||
```
|
||
- 推送到远程：
|
||
```
|
||
git push -u origin develop-framework
|
||
```
|
||
|
||
## 合并到主分支（首选 PR 流程）
|
||
- 方式一：在 Gitea 发起 PR（推荐）
|
||
- 目标：`develop-framework` -> `main-framework`
|
||
- 检查 CI 构建通过、代码评审通过后合并。
|
||
- 合并策略建议：`Squash` 或 `Rebase and merge` 保持主分支提交整洁。
|
||
|
||
- 方式二：命令行快速合并（仅在无保护、需要紧急修复时使用）
|
||
```
|
||
# 确保主分支最新
|
||
git checkout main-framework
|
||
git pull --ff-only
|
||
|
||
# 将主分支变更应用到开发分支，减少合并冲突
|
||
git checkout develop-framework
|
||
git rebase main-framework
|
||
# 解决冲突后：
|
||
# git add <files>
|
||
# git rebase --continue
|
||
|
||
# 回到主分支并合并（优先快进）
|
||
git checkout main-framework
|
||
git merge --ff-only develop-framework || git merge --no-ff develop-framework
|
||
|
||
# 推送主分支
|
||
git push origin main-framework
|
||
```
|
||
|
||
## 版本与标签（发布规范）
|
||
- 采用语义化版本：`vMAJOR.MINOR.PATCH`（示例：`v1.0.0`）。
|
||
- 打标签并推送：
|
||
```
|
||
# 核心检查：构建通过、基本功能自测 OK
|
||
mvn -B -DskipTests clean package
|
||
|
||
# 标签与推送
|
||
git tag -a v1.0.0 -m "release: framework v1.0.0 可执行JAR"
|
||
git push origin v1.0.0
|
||
```
|
||
|
||
## 构建校验（必须）
|
||
- 本地快速验证：
|
||
```
|
||
# 打包
|
||
mvn -q -DskipTests package
|
||
# 启动（dev）
|
||
java -jar target/platform-1.0.jar --spring.profiles.active=dev
|
||
# 浏览器访问（默认端口）
|
||
http://localhost:8093/
|
||
```
|
||
- 如果使用前端集成：
|
||
- POM 已配置在 `generate-resources` 阶段执行 `npm install` 与 `npm run build:mvn`。
|
||
- 静态资源复制（`frontend/dist` -> `src/main/resources/static`）可通过 `maven-resources-plugin` 控制；必要时启用/关闭 `<skip>` 或使用 Maven Profile 控制。
|
||
|
||
## 分支保护与权限（建议在 Gitea 设置）
|
||
- 保护 `main-framework`：
|
||
- 禁止直接 push 到主分支，仅允许通过 PR 合并。
|
||
- 最少 1 人审核，CI 必须通过。
|
||
- 禁止强制推送（force push）。
|
||
- 标签权限：仅发布管理员可打 `release` 标签。
|
||
|
||
## 常见场景与命令速查
|
||
- 同步远程状态（清理过期分支）：
|
||
```
|
||
git fetch --all --prune
|
||
```
|
||
- 创建特性分支：
|
||
```
|
||
git checkout develop-framework
|
||
git pull --ff-only
|
||
git checkout -b feature/<name>
|
||
```
|
||
- 将特性分支合并回开发分支：
|
||
```
|
||
git checkout develop-framework
|
||
git merge --no-ff feature/<name>
|
||
git push origin develop-framework
|
||
```
|
||
- 更新主分支并合并开发分支（CLI）：
|
||
```
|
||
git checkout main-framework
|
||
git pull --ff-only
|
||
git merge --ff-only develop-framework || git merge --no-ff develop-framework
|
||
git push origin main-framework
|
||
```
|
||
- 回滚错误提交：
|
||
```
|
||
# 回滚指定提交（保留历史）
|
||
git revert <commit_sha>
|
||
# 或回退到某版本（谨慎，可能重写历史）
|
||
git reset --hard <commit_sha>
|
||
git push -f origin <branch> # 若分支受保护，需取消保护或走 PR revert
|
||
```
|
||
|
||
## 冲突处理指南
|
||
- Rebase 阶段冲突：
|
||
- 编辑冲突文件，确保以 `main-framework` 为基线保留正确逻辑。
|
||
- 逐个解决后：`git add <file>`，继续：`git rebase --continue`。
|
||
- Merge 阶段冲突：
|
||
- 优先在 `develop-framework` 解决，再合并到 `main-framework`，减少主分支污染。
|
||
|
||
## 提交规范建议（Conventional Commits）
|
||
- 前缀示例：`feat`、`fix`、`docs`、`refactor`、`perf`、`test`、`build`、`chore`。
|
||
- 示例：`feat: 前端静态资源复制支持 Profile 开关`。
|
||
|
||
## CI/CD 建议
|
||
- CI：
|
||
- `mvn -B -DskipTests clean package`
|
||
- 单元测试、依赖安全扫描、代码质量检查
|
||
- CD：
|
||
- 根据标签构建镜像，注入敏感配置（环境变量/密钥管理）。
|
||
|
||
## 问题排查
|
||
- 构建失败：检查 `pom.xml` 插件配置，先本地运行 `mvn -e package` 查看详细栈。
|
||
- 端口冲突：调整 `server.port` 或释放占用端口。
|
||
- npm 警告/冲突：在 `frontend/` 内单独 `npm install && npm run build`，再复制到后端静态目录。
|
||
|
||
---
|
||
|
||
如需将资源复制与文档生成改为按需开关（Maven Profile），可在 `pom.xml` 中添加 Profile 并通过 `-P <profile>` 控制。需要我帮助你落地 Profile 与分支保护脚本，请告诉我你的偏好（例如是否必须走 PR）。 |