m2pool_docs/document.md

📦 代码与版本管理规范

1. 版本一致性要求

• 所有模块必须采用统一的版本依赖（如 go.mod、package.json 等）。
• 版本号需遵循 语义化版本规范 (SemVer)，如：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 规范（需包含以下内容）

• ✅ 编译命令（示例）：

  go build -o ./bin/app main.go
  

• ✅ 启动命令：

  ./bin/app --config ./configs/config.yaml
  

• ✅ 打包说明（如 Dockerfile、压缩包结构等）；
• ✅ 配置文件结构说明(其他如.conf、.ini、.json、.yaml等配置文件按照规范命名，并说明配置项含义和用途)：

  server:
    port: 8080
  database:
    host: localhost
    name: project_db
  

• ✅ 各项配置说明或链接到配置文档。

---

8. 数据结构与初始化要求

• 所有数据库表结构必须提供初始化脚本：

  /db
    ├── init.sql
    └── migration/
  

• 禁止手动创建、删除、修改数据表和表结构，尽量避免依赖人工操作数据库；
• 推荐使用自动迁移工具（如 Flyway、Goose、gormigrate）进行结构升级控制。

---