docs/Git-Management

Fork 0

Files

许轲 b4cf9e2ddf 更新 README.md

2025-08-22 10:52:32 +08:00

17 KiB

Raw Blame History

Git 管理规范

1. 版本控制基础

使用 Git 进行版本控制，并遵循以下基本原则:

所有代码更改必须通过 Git 提交，并推送至远程仓库。
每次提交必须包括清晰、简洁且具描述性的提交信息，确保团队成员能够轻松理解变更的目的和内容。
严禁直接在 main 分支上进行开发。所有功能开发必须通过独立分支进行。

2. 分支管理

本项目采用以下分支策略进行代码管理:

2.1 主分支 (`main`)

用途: main 分支始终保持项目的稳定版本，且此分支的代码随时可以部署到生产环境。
更新规则: 仅允许经过充分测试并审查的代码合并到 main 分支。每次从 dev 或 release 分支合并到 main 时，必须打上版本标签。

2.2 开发分支 (`dev`)

用途: dev 分支是所有开发工作的集成分支。所有的新功能开发应首先合并至 dev 分支，并经过集成测试后再合并到 main。
更新规则: 所有功能开发完成后，应合并至 dev 分支进行集成测试，确认没有问题后再合并到 main。

2.3 功能分支 (`feature/*`)

用途: 每个新功能的开发都应从 dev 分支创建一个独立的功能分支。
命名规范: feature/功能描述，例如: feature/ast-folding、feature/user-cli。所有分支名称应使用小写字母，并且使用破折号（-）分隔单词。
开发流程:
1. 从 dev 分支拉取最新代码。
2. 完成功能开发后，在本地提交代码并推送至远程仓库。
3. 创建拉取请求（PR），并合并到 dev 分支。

2.4 修复分支 (`bugfix/*`)

用途: 用于修复 Bug，修复分支可以从 dev 或 main 分支创建。
命名规范: bugfix/bug描述，例如: bugfix/fix-ast-error。
开发流程:
1. 从 dev 或 main 分支拉取最新代码。
2. 完成修复后，提交修改并推送至远程仓库。
3. 创建拉取请求（PR），并合并到相应分支。

2.5 发布分支 (`release/*`)

用途: 当 dev 分支的功能开发完成且准备发布时，应创建一个 release 分支进行发布准备。
命名规范: release/vX.X.X，例如: release/v1.0.0。
开发流程:
1. 从 dev 分支创建 release 分支。
2. 在 release 分支上进行版本发布的最终准备工作，如文档更新、版本号调整等。
3. 完成发布准备后，将 release 分支合并至 main 并打上版本标签，随后将变更合并回 dev 分支。

2.6 热修复分支 (`hotfix/*`)

用途: 当生产环境中发现紧急问题（如 Bug 或系统崩溃等），需在 main 分支上进行快速修复时，应创建一个 hotfix 分支进行修复。
命名规范: hotfix/bug描述，例如: hotfix/fix-production-crash。
开发流程:
1. 从 main 分支创建 hotfix 分支，确保该分支包含生产环境中最新的稳定版本。
2. 在 hotfix 分支上进行问题修复和相关调整。
3. 完成修复后，提交修改并推送至远程仓库。
4. 创建拉取请求（PR），将 hotfix 分支合并至 main 分支并打上版本标签，确保生产环境修复生效。
5. 将修复后的变更合并回 dev 分支，确保所有的修复和调整同步到开发分支，防止后续开发中出现同样的问题。
6. 回滚策略: 如果热修复未能解决问题，立即回滚合并，删除 hotfix 分支并通知团队，确保不影响生产环境。

2.7 分支流程图

flowchart LR
  %% ---------- Core dev cycle ----------
  subgraph CORE[Core Flow]
    direction LR
    F[Feature] --> D[Dev] --> R[Release] --> M[Main] --> P[Production]
    R --> D
  end

  %% ---------- Fix streams grouped ----------
  subgraph FIX[Fix Streams]
    direction TB
    B[Bugfix]
    H[Hotfix]
  end

  %% Bugfix: can start from Dev or Main, merges back to both
  D -. create .-> B
  M -. create .-> B
  B --> D
  B --> M

  %% Hotfix: from Main, then merge back to Main & Dev
  M -. create .-> H
  H --> M
  H --> D

  %% ---------- Styling ----------
  classDef core fill:#EEF5FF,stroke:#5B8DEF,stroke-width:2px,rx:10,ry:10;
  classDef branch fill:#F6F5FF,stroke:#9B87F5,rx:10,ry:10;
  classDef hot fill:#FFF5F5,stroke:#F56565,stroke-width:2px,rx:10,ry:10;
  classDef env fill:#E8FFF8,stroke:#2C7A7B,stroke-width:2px,rx:10,ry:10;

  class D,R,M core;
  class F,B branch;
  class H hot;
  class P env;

简要说明

主流程：所有开发都在 feature/ 或 bugfix/ 分支，合并至 dev，再经过 release/ 到 main。
发布：release/ 分支只用于准备发布，合并后要打 Tag 并同步回 dev。
热修复：hotfix/ 从 main 分支拉出，紧急修复后要同时同步回 main 和 dev。
所有分支 通过 PR（拉取请求） 合并，需经过代码审查。

3. 提交规范

为确保提交信息清晰且易于理解，遵循以下提交规范:

3.1 提交信息格式

提交信息应简洁且具有描述性，格式如下:

[类型] 描述

详细描述（可选）

提交类型

feat: 新增功能
fix: 修复 Bug
docs: 文档更新
style: 代码格式调整（不影响功能）
refactor: 代码重构
test: 增加/修改测试
chore: 工具配置等其他杂项任务
ci: 持续集成相关改动
perf: 性能优化

示例

feat: 添加 IR 折叠功能
fix: 修复问题 Y（原因: X bug，解决方案: Z）
docs: 更新 API 文档
refactor: 优化 AST 逻辑

3.2 提交实践

提交时，请确保代码已完成并通过所有相关测试。
每次提交应仅包含少量且相关的变更，避免一次性提交过多内容，以便于追踪和管理。

4. 拉取请求（PR）与代码审查

4.1 拉取请求流程

开发者在完成功能或修复后，创建 PR，将其分支合并至 dev 或 main 分支。
其他团队成员进行代码审查，重点检查代码质量、功能完整性及测试覆盖率。
审查通过后，PR 将被合并,PR 合并后删除 feature/bugfix 分支，避免仓库臃肿。

4.2 代码审查

所有 PR 必须经过至少一名开发者的代码审查。
审查时应关注以下方面(可简化步骤):
- 代码是否符合项目的编码规范。(可选)
- 是否提供了足够的单元测试覆盖。(可选)
- 是否存在冗余代码或复杂度过高的部分。(可选)
- 功能是否按预期工作。(必须)
- 审查者应在 PR 中提供反馈，确保代码质量高，符合团队要求。(可选)

5. 版本发布

5.1 打标签

每当版本准备发布时，应在 main 分支上打上版本标签:

版本号规则: 采用语义化版本控制（SemVer）格式，版本号由三部分组成: 主版本号.次版本号.修订号（例如: v1.0.0）。
- 主版本号（Major）：当做了不兼容的 API 变更，或有较大重构影响使用方式时，递增主版本号，例如 v2.0.0。
- 次版本号（Minor）：当新增了向下兼容的新功能，且未破坏已有接口时，递增次版本号，例如 v1.1.0。
- 修订号（Patch）：当进行向下兼容的问题修复或小改进，递增修订号，例如 v1.0.1。
标签命令:
```
git tag v1.0.0
git push origin v1.0.0
```
注意事项:
- 所有版本标签必须基于 main 分支最新的稳定提交。

5.2 发布流程

确保所有功能已合并至 dev 分支，并通过集成测试。
从 dev 分支创建 release 分支，进行版本发布的准备工作。
在 release 分支上完成最终修改，如文档更新和版本号调整。
将 release 分支合并至 main 并打上版本标签。
将 release 分支的变更合并回 dev，确保所有修复和改动在开发分支中得到同步。

5.3 发布后

发布版本后，团队成员应确保将 main 分支的最新代码拉取到本地，以保持代码库的同步。
如出现生产环境问题，应及时创建 hotfix 分支进行紧急修复，并尽快发布。

6. 工单（Issue ）

6.1 Issue 介绍

用途: Issue 用于跟踪项目中的任务、功能需求、Bug 报告以及改进建议。每个 Issue 都应有明确的描述，方便开发者理解并处理。
基本要求:
- 每个功能开发、Bug 修复都应有对应的 Issue。
- 在提交 PR 时，应在描述中关联对应的 Issue（如 close #123 或 resolve #123）。
- Issue 状态应及时更新，避免长期挂起。

6.2 Issue 分类

标签名	说明	用途举例
类型标签
`bug`	缺陷或错误修复	修复功能异常、错误行为
`feature`	新功能开发	开发新模块、新接口
`enhancement`	功能改进或优化	性能优化、界面优化
`documentation`	文档相关	修改/补充文档
`test`	测试相关	单元测试、集成测试
`question`	需要进一步澄清	提问、需求澄清
`wontfix`	不会修复	不予处理的问题
优先级标签
`high`	高优先级，需立即处理	紧急缺陷、重大阻塞
`medium`	中等优先级，近期处理	普通功能需求
`low`	低优先级，长期计划	次要改进、未来规划

6.3 Issue 流程

创建 Issue
- 明确问题或需求，写清楚背景、预期结果和实际情况。
- 必要时提供截图、日志或代码片段。
分配 Issue
- 项目负责人或团队成员可将 Issue 分配给具体开发者。
- 复杂的 Issue 建议先进行评估，再拆分为子任务。
处理 Issue
- 开发者在新建分支（如 feature/*、bugfix/*、hotfix/*）时，应在分支说明或 PR 中关联对应的 Issue。
- 处理完成后，提交 PR 并关联 Issue。
关闭 Issue
- 合并 PR 前需要关闭关联 Issue。
- 如果问题未解决，应重新打开或创建新的 Issue。

6.4 Issue 最佳实践

描述清晰：避免模糊描述，如“修复报错”；应写明“修复用户登录时因 token 校验失败导致的 500 错误”。
一个 Issue 只包含一个问题：避免一个 Issue 同时涉及多个 Bug 或功能需求。
保持更新：在处理过程中，及时补充进展，方便团队成员了解状态。
结合 Milestone：将 Issue 归档到迭代或版本里，保证任务有明确的交付目标。

7. 里程碑（Milestone）

7.1 里程碑用途

规划目标：里程碑用于组织和跟踪一组 Issue/PR，代表一次迭代、一个版本或一个阶段性的目标。
可视化进度：通过里程碑的完成率，团队可以直观了解当前迭代进度。
发布关联：每个正式发布版本都应关联到一个里程碑，确保版本内容可追踪。

7.2 创建规则

新建里程碑时，应填写：
- 标题：使用统一格式，例如 v1.0.0。
- 描述：简要说明该里程碑的目标和范围。
- 截止日期：设定完成时间，帮助团队明确交付周期。

7.3 使用规范

Issue 关联：
- 每个新建的 Issue 必须尽量关联到一个里程碑。
- 未确定目标的 Issue 可先放在 “Backlog” 或 “待规划”里程碑。
PR 关联：
- PR 在合并时，应确保它关联的 Issue 属于当前里程碑。
进度管理：
- 里程碑进度 = 已关闭 Issue 数量 / 总 Issue 数量。
- 项目负责人需定期检查未完成的 Issue，并协调优先级。

7.4 关闭规则

当里程碑中所有 Issue 已关闭，或者版本已发布，即可关闭里程碑。
如果有遗留 Issue，需在关闭前明确处理方式：
- 推迟：迁移到下一个里程碑。
- 废弃：如不再需要，则关闭并标记 wontfix。

7.5 检查流程

迭代中期检查：
- 项目负责人应在迭代进行中期，检查里程碑下 Issue 的进展情况；
- 对进度滞后的任务，及时协调资源或调整优先级。
迭代结束检查：
- 在里程碑截止日期前，确认所有关键任务是否完成；
- 未完成的任务需记录原因，并决定是否推迟或关闭。

7.6 最佳实践

保持一致性：所有版本发布必须有对应的里程碑，避免出现“无里程碑”的版本。
小步快跑：一个里程碑的范围应合理，不宜包含过多任务，避免长期悬而未决。
结合项目与标签：
- 通过 项目（Project Board） 可视化任务流转；
- 通过 标签（Label） 辅助分类和优先级管理。
透明共享：所有团队成员应能随时查看里程碑进度，确保信息透明。

7.7 角色与职责

项目负责人
- 负责创建和维护里程碑；
- 确保 Issue/PR 按时关联到正确的里程碑；
- 定期组织里程碑检查会议，推动任务完成。
开发者
- 在创建 Issue 或提交 PR 时主动关联里程碑；
- 按时完成任务，若有延期风险需提前反馈。
审查者
- 确保代码合并时，相关的 Issue 与里程碑状态保持一致；
- 协助确认任务是否达到关闭条件。

8. 项目（Project）

8.1 项目用途

任务可视化：通过看板（Kanban）方式直观展示任务进度。
迭代管理：结合里程碑（Milestone），按迭代或版本管理任务。
跨仓库协作：在组织级项目中统一管理多个仓库的任务。
进度跟踪：方便团队随时了解任务状态和当前瓶颈。

8.2 项目类型

仓库级项目：适用于单一仓库，管理与该仓库相关的 Issue/PR。
组织级项目：跨多个仓库，适用于大型项目或产品团队。

8.3 项目结构

每个项目默认采用 四列看板工作流：

列名	含义	示例任务
`Backlog`	待规划任务池	收集的新需求、改进建议
`To Do`	已排期待执行任务	当前迭代计划任务
`In Progress`	正在进行的任务	功能开发、Bug 修复
`Done`	已完成任务	已合并 PR、完成的文档更新

团队可在必要时新增列，例如 Blocked、QA，但推荐保持简洁。

8.4 使用规范

任务录入
- 所有需求、Bug、改进均以 Issue 形式创建，再添加到项目中。
- 避免直接在项目中新增“空卡片”，确保信息集中在 Issue/PR。
任务分配
- 项目负责人将新建 Issue 拖入 Backlog；
- 在迭代规划时放入 To Do 并分配负责人；
- 设置优先级标签（high/medium/low）。
任务推进
- 开发者领取任务后，将其移至 In Progress；
- 任务完成并合并 PR 后，移动到 Done。
迭代关联
- 所有 To Do 中的任务需关联到对应里程碑；
- 确保项目进度与里程碑目标保持一致。

8.5 检查流程

每日/例会检查：快速查看 In Progress 状态，排查阻塞。
迭代中期检查：负责人检查里程碑完成度，必要时调整 To Do 范围。
迭代结束检查：确认 Done 是否覆盖所有计划任务，遗留任务迁移到下个里程碑或保留在 Backlog。

8.6 最佳实践

限制在制品（WIP）：In Progress 中任务数量不宜过多，避免分散精力。
保持透明：所有团队成员均应在项目中更新任务状态，避免信息滞后。
结合标签和里程碑：
- 标签（分类、优先级） → 任务属性
- 里程碑（版本/迭代） → 目标规划
- 项目（看板） → 执行过程

8.7 角色与职责

项目负责人
- 创建与维护项目；
- 规划任务优先级，分配负责人；
- 定期检查进度并协调资源。
开发者
- 主动更新任务状态（拖动 Issue 卡片）；
- 在 PR 中关联 Issue 和里程碑；
- 按计划完成任务。
审查者/测试人员
- 验证任务是否符合预期；
- 确认通过后推动任务进入 Done。

8.8 项目流程图

flowchart LR
    B[Backlog<br/>待规划任务] --> T[To Do<br/>已排期待执行]
    T --> P[In Progress<br/>正在进行]
    P --> D[Done<br/>已完成]

    %% Styling
    classDef backlog fill:#F0F8FF,stroke:#4682B4,stroke-width:2px,rx:10,ry:10;
    classDef todo fill:#FFF8DC,stroke:#DAA520,stroke-width:2px,rx:10,ry:10;
    classDef progress fill:#E6FFFA,stroke:#2E8B57,stroke-width:2px,rx:10,ry:10;
    classDef done fill:#F0FFF0,stroke:#228B22,stroke-width:2px,rx:10,ry:10;

    class B backlog
    class T todo
    class P progress
    class D done

17 KiB Raw Blame History Unescape Escape

Git 管理规范

1. 版本控制基础

2. 分支管理

2.1 主分支 (main)

2.2 开发分支 (dev)

2.3 功能分支 (feature/*)

2.4 修复分支 (bugfix/*)

2.5 发布分支 (release/*)

2.6 热修复分支 (hotfix/*)

2.7 分支流程图

简要说明

3. 提交规范

3.1 提交信息格式

提交类型

示例

3.2 提交实践

4. 拉取请求（PR）与代码审查

4.1 拉取请求流程

4.2 代码审查

5. 版本发布

5.1 打标签

5.2 发布流程

5.3 发布后

6. 工单（Issue ）

6.1 Issue 介绍

6.2 Issue 分类

6.3 Issue 流程

6.4 Issue 最佳实践

7. 里程碑（Milestone）

7.1 里程碑用途

7.2 创建规则

7.3 使用规范

7.4 关闭规则

7.5 检查流程

7.6 最佳实践

7.7 角色与职责

8. 项目（Project）

8.1 项目用途

8.2 项目类型

8.3 项目结构

8.4 使用规范

8.5 检查流程

8.6 最佳实践

8.7 角色与职责

8.8 项目流程图

17 KiB

Raw Blame History

2.1 主分支 (`main`)

2.2 开发分支 (`dev`)

2.3 功能分支 (`feature/*`)

2.4 修复分支 (`bugfix/*`)

2.5 发布分支 (`release/*`)

2.6 热修复分支 (`hotfix/*`)