119 lines
4.8 KiB
Markdown
119 lines
4.8 KiB
Markdown
# 📦 代码与版本管理规范
|
||
|
||
## 1. 版本一致性要求
|
||
|
||
- 所有模块必须采用统一的版本依赖（如 go.mod、package.json 等）。
|
||
- 版本号需遵循 [语义化版本规范 (SemVer)](https://semver.org/lang/zh-CN/)，如：`v1.0.0`、`v1.1.0-beta`。
|
||
- 不同模块版本需保持兼容，不允许出现版本冲突。
|
||
|
||
---
|
||
|
||
## 2. 需求文档与提交代码对齐
|
||
|
||
- 提交代码必须严格对应当前版本的需求文档。
|
||
- 禁止提交未在需求文档中定义的功能代码或逻辑。
|
||
- 建议每次提交记录中引用需求编号或链接。
|
||
---
|
||
### 2.1 分支管理
|
||
|
||
- 主分支：`main`，用于存放发布的稳定版本
|
||
- 开发分支：`dev`，用于存放开发中的代码
|
||
- bug修复分支：`bugfix/xxx`，用于存放bug修复的代码
|
||
- 预发布分支：`release/xxx`，用于存放预发布的代码
|
||
- 线上紧急修复分支：`hotfix/xxx`，用于存放线上紧急修复的代码
|
||
|
||
### 2.2 提交流程
|
||
|
||
- 先选择本次提交内容的分支，如`git checkout dev`，切换到开发分支
|
||
- 选择分之后使用`git pull`拉取最新代码
|
||
- 使用`git add .`添加本次提交的内容，如果遇到冲突，需要先手动解决冲突
|
||
- 解决冲突后，使用`git commit -m "提交信息"`提交本次修改，提交信息遵循：`[类型] [模块] [描述]`，例如：`fix database connection error`
|
||
- 提交后使用`git push origin dev`将本次修改推送到远程分支
|
||
- 禁止`main`分支提交，向`release/xxx`和`hotfix/xxx`分支提交代码需经过审核
|
||
- `bugfix/xxx`、`release/xxx`、`hotfix/xxx`分支合并到`main`分支后，需删除该分支
|
||
|
||
### 2.3 常见git命令
|
||
|
||
- `git checkout <branch>` 切换分支, 例如：`git checkout dev` 切换到dev分支
|
||
- `git pull origin <branch>` 拉取最新代码，例如：`git pull origin dev` 拉取远程dev分支最新代码
|
||
- `git diff` 查看当前修改内容，引申出 `git diff <file>` 查看指定文件的修改内容，`git diff > diff.txt` 将修改内容输出到diff.txt文件中，`git diff <commit_id1> <commit_id2> > diff.txt` 将两个commit之间的修改内容输出到diff.txt文件中等等
|
||
- `git add .` 添加所有修改到暂存区，`git add <file>` 添加指定文件到暂存区，`git reset <file>` 撤销指定文件的修改，`git reset` 撤销所有修改
|
||
- `git commit -m "提交信息"` 提交暂存区修改，`git commit --amend` 修改最近一次提交信息
|
||
- `git push origin <branch>` 推送本地分支到远程分支，`git push origin <branch>:<remote_branch>` 推送本地分支到远程分支，`git push origin :<remote_branch>` 删除远程分支
|
||
- `git remote -v` 查看远程仓库地址，`git remote add <name> <url>` 添加远程仓库地址，`git remote remove <name>` 删除远程仓库地址
|
||
|
||
## 3. 版本发布要求
|
||
|
||
- 发布版本需提供对应测试报告（功能测试、回归测试、异常测试）。
|
||
- 仅在测试报告审核通过后方可发布版本。
|
||
- 所有发布记录需归档并记录变更日志（详见第 6 节）。
|
||
- 版本发布即为稳定版本，禁止修改其代码。
|
||
|
||
---
|
||
|
||
## 4. 环境搭建与部署要求
|
||
|
||
- ✅ 开发环境与测试环境由开发/测试人员自行搭建；
|
||
- 🚫 生产环境搭建需提供《部署说明文档》，通过审核后方可执行；
|
||
- 建议本地化部署测试生产模拟环境；
|
||
- 示例目录结构：
|
||
```
|
||
/env
|
||
├── dev.env
|
||
├── test.env
|
||
└── prod.env
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 环境隔离规范
|
||
|
||
- 所有代码、数据库及配置必须区分开发、测试、生产环境；
|
||
- 严禁不同环境代码或数据交叉使用；
|
||
- 推荐通过 `.env` 文件或配置中心隔离不同环境配置项。
|
||
|
||
---
|
||
|
||
## 6. 上线与版本基线管理
|
||
|
||
- 各模块首次上线作为版本基线（如 `v1.0.0`）；
|
||
- 多模块协作时需同步约定接口及数据结构；
|
||
- 使用 `CHANGELOG.md` 文件记录版本更新内容。
|
||
|
||
---
|
||
|
||
## 7. README 规范（需包含以下内容）
|
||
|
||
- ✅ 编译命令（示例）：
|
||
```bash
|
||
go build -o ./bin/app main.go
|
||
```
|
||
- ✅ 启动命令：
|
||
```bash
|
||
./bin/app --config ./configs/config.yaml
|
||
```
|
||
- ✅ 打包说明（如 Dockerfile、压缩包结构等）；
|
||
- ✅ 配置文件结构说明(其他如.conf、.ini、.json、.yaml等配置文件按照规范命名，并说明配置项含义和用途)：
|
||
```yaml
|
||
server:
|
||
port: 8080
|
||
database:
|
||
host: localhost
|
||
name: project_db
|
||
```
|
||
- ✅ 各项配置说明或链接到配置文档。
|
||
|
||
---
|
||
|
||
## 8. 数据结构与初始化要求
|
||
|
||
- 所有数据库表结构必须提供初始化脚本：
|
||
```
|
||
/db
|
||
├── init.sql
|
||
└── migration/
|
||
```
|
||
- 禁止手动创建、删除、修改数据表和表结构，尽量避免依赖人工操作数据库；
|
||
- 推荐使用自动迁移工具（如 Flyway、Goose、gormigrate）进行结构升级控制。
|
||
|
||
--- |