# Git 管理规范 ## 1. 版本控制基础 使用 Git 进行版本控制，并遵循以下基本原则: * 所有代码更改必须通过 Git 提交，并推送至远程仓库，仓库名称示例: `Git-Management`。 * 每次提交必须包括清晰、简洁且具描述性的提交信息，确保团队成员能够轻松理解变更的目的和内容。 * 严禁直接在 `main` 分支上进行开发。所有功能开发必须通过独立分支进行。 --- ## 2. 分支管理 本项目采用以下分支策略进行代码管理，分为 **主线分支（长期存在）** 和 **辅助分支（短期存在）** 两个层级。 ### 2.1 主线分支（长期存在） #### `main` 分支 * **用途**: * 始终保持项目的稳定版本； * 此分支的代码随时可以部署到生产环境。 * **更新规则**: * 严禁直接在 `main` 分支上开发； * 仅允许经过充分测试并审查的代码合并； * 每次从 `release` 分支合并到 `main` 时，必须打上版本标签。 #### `dev` 分支 * **用途**: * 集成分支，是所有开发工作的汇集点； * 所有新功能和修复分支都应合并至 `dev` 进行集成测试。 * **更新规则**: * 功能开发完成后 → 合并至 `dev` ； * `dev` 分支应保持可运行状态，避免不稳定代码长期停留。 ### 2.2 辅助分支（短期存在，用完即删） #### 功能分支 (`feature/*`) * **用途**: * 用于新功能开发，每个功能一个独立分支。 * **命名规范**: * `feature/功能描述`，如: `feature/ast-folding`、`feature/user-cli`； * 分支名称统一使用小写字母，单词间用破折号（`-`）分隔。 * **开发流程**: 1. 从 `dev` 分支拉取最新代码并创建分支； 2. 完成功能开发后，本地提交并推送到远程仓库； 3. 创建拉取请求（PR），合并回 `dev` 分支。 #### 修复分支 (`bugfix/*`) * **用途**: * 用于修复一般性 Bug； * **命名规范**: * `bugfix/bug描述`，如: `bugfix/fix-ast-error`。 * 分支名称统一使用小写字母，单词间用破折号（`-`）分隔。 * **开发流程**: 1. 从 `dev` 分支拉取最新代码； 2. 完成修复后提交并推送到远程仓库； 3. 创建拉取请求（PR），合并回相应分支。 #### 发布分支 (`release/*`) * **用途**: * 用于版本发布的准备（文档更新、版本号调整等）； * 保证发布过程稳定，不受未完成功能的影响。 * **命名规范**: * `release/vX.X.X`，如: `release/v1.0.0`。 * **开发流程**: 1. 从 `dev` 分支创建 `release` 分支； 2. 在 `release` 分支完成发布前准备工作（文档、版本号、配置修改等）； 3. 准备完成后，将 `release` 分支合并至 `main` 并打上版本标签； 4. 将 `release` 分支变更同步合并回 `dev`，保证开发分支与主分支一致。 #### 热修复分支 (`hotfix/*`) * **用途**: * 用于生产环境中的紧急问题修复（如严重 Bug、系统崩溃等）； * 保证在最短时间内修复并恢复服务。 * **命名规范**: * `hotfix/bug描述`，如: `hotfix/fix-production-crash`。 * **开发流程**: 1. 从 `main` 分支创建 `hotfix` 分支，保证包含生产环境的最新稳定版本； 2. 在 `hotfix` 分支完成修复并提交推送； 3. 创建拉取请求（PR），将 `hotfix` 分支合并至 `main` 并打上版本标签； 4. 同时将修复内容合并回 `dev`，避免后续开发再次出现同样问题； 5. **回滚策略**：若修复未能解决问题，立即回滚合并，删除 `hotfix` 分支并通知团队，确保不影响生产环境。 ### 2.7 分支流程图 ```mermaid flowchart LR %% ---------- Core dev cycle ---------- subgraph CORE[ ] direction LR B[Bugfix] H[Hotfix] F[Feature] D[Dev] R[Release] M[Main] P[Production] F --> D D -. create .-> R R --> M R --> D D -. create .-> F M --Tag--> P M --- D end %% Bugfix: can start from Dev or Main, merges back to both D -. create .-> B B --> D %% Hotfix: from Main, then merge back to Main M -. create .-> H H --> M %% ---------- 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,M core; class F,B,R,H branch; 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 提交实践 * 提交信息可使用 `jetbrains 插件` [Lingma - 阿里云 AI 编程助手](https://plugins.jetbrains.com/plugin/17809-lingma--alibaba-cloud-ai-coding-assistant) 快速生成初版。 >不能生成后直接提交因为生成的 `提交类型` 会生成不符合本规范的版本,但是 `详细描述` 可以使用。 * 提交时，请确保代码是否符合项目的 [编码规范](https://gitea.fireflydt.com/docs/Encoding-Specification)。 * 每次提交应仅包含少量且相关的变更，避免一次性提交过多内容，以便于追踪和管理。 --- ## 4. 拉取请求（PR）与代码审查 ### 4.1 拉取请求流程 1. 开发者在完成功能或修复后，创建 PR，将其分支合并至 `dev` 或 `main` 分支。 2. 其他团队成员进行代码审查，重点检查代码质量、功能完整性。 3. 审查通过后，PR 将被合并,PR 合并后删除 `feature/bugfix` 分支，避免仓库臃肿。 ### 4.2 代码审查 * 所有 PR 必须经过至少一名开发者的代码审查。 * 审查时应关注功能是否按预期工作。 --- ## 5. 版本发布 ### 5.1 打标签 每当版本准备发布时，应在 `main` 分支上打上版本标签: * **版本号规则**: 采用语义化版本控制（SemVer）格式，版本号由三部分组成: `主版本号.次版本号.修订号`（例如: `v1.0.0`）。 * **主版本号（Major）**：当做了**不兼容的 API 变更**，或有较大重构影响使用方式时，递增主版本号，例如 `v2.0.0`。 * **次版本号（Minor）**：当新增了**向下兼容的新功能**，且未破坏已有接口时，递增次版本号，例如 `v1.1.0`。 * **修订号（Patch）**：当进行**向下兼容的问题修复或小改进**，递增修订号，例如 `v1.0.1`。 * **标签命令**: ```bash git tag v1.0.0 git push origin v1.0.0 ``` * **注意事项**: * 所有版本标签必须基于 `main` 分支最新的稳定提交。 * 历史项目使用 Gitea 托管以 `v1.0.0` 为初始版本。 * 新项目使用 Gitea 托管以 `v0.1.0` 为初始版本。 ### 5.2 发布流程 1. 确保所有功能已合并至 `dev` 分支，并通过集成测试。 2. 从 `dev` 分支创建 `release` 分支，进行版本发布的准备工作。 3. 在 `release` 分支上完成最终修改，如文档更新和版本号调整。 4. 将 `release` 分支合并至 `main` 并打上版本标签。 5. 将 `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 流程 1. **创建 Issue** * 明确问题或需求，写清楚背景、预期结果和实际情况。 * 必要时提供截图、日志或代码片段。 2. **分配 Issue** * 项目负责人或团队成员可将 Issue 分配给具体开发者。 * 复杂的 Issue 建议先进行评估，再拆分为子任务。 3. **处理 Issue** * 开发者在新建分支（如 `feature/*`、`bugfix/*`、`hotfix/*`）时，应在分支说明或 PR 中关联对应的 Issue。 * 处理完成后，提交 PR 并关联 Issue。 4. **关闭 Issue** * 合并 PR 前需要关闭关联 Issue。 * 如果问题未解决，应重新打开或创建新的 Issue。 ### 6.4 Issue 最佳实践 * **描述清晰**：避免模糊描述，如“修复报错”；应写明“修复用户登录时因 token 校验失败导致的 500 错误”。 * **一个 Issue 只包含一个问题**：避免一个 Issue 同时涉及多个 Bug 或功能需求。 * **保持更新**：在处理过程中，及时补充进展，方便团队成员了解状态。 * **关联 Milestone**：将 Issue 关联 Milestone，保证任务有明确的交付目标。 ```mermaid flowchart LR A[创建 Issue
📝] --> B[分配 Issue
👤] B --> C[处理 Issue
🔨] C --> D[关闭 Issue
✅] %% 详细说明 A -.-> A1(明确问题/需求，背景、预期、实际) A -.-> A2(必要时截图/日志/代码) B -.-> B1(分配给具体开发者) C -.-> C2(PR 关联 Issue) D -.-> D1(PR 合并前关闭 Issue) D -.-> D2(未解决可重开或新建) %% 样式 classDef main fill:#E8F6FF,stroke:#4A90E2,stroke-width:2px,rx:10,ry:10; classDef detail fill:#F6F8FA,stroke:#B5B5B5,rx:10,ry:10; class A,B,C,D main; class A1,A2,B1,B2,C1,C2,D1,D2 detail; ``` ## 7. 里程碑（Milestone） ### 7.1 里程碑用途 * **规划目标**：里程碑用于组织和跟踪一组 Issue/PR，代表一次迭代、一个版本或一个阶段性的目标。 * **可视化进度**：通过里程碑的完成率，团队可以直观了解当前迭代进度。 * **发布关联**：每个正式发布版本都应关联到一个里程碑，确保版本内容可追踪。 ### 7.2 创建规则 * 新建里程碑时，应填写： * **标题**：使用统一格式，例如 `v1.0.0`。 * **描述**：简要说明该里程碑的目标和范围。 * **截止日期**：设定完成时间，帮助团队明确交付周期(可选)。 ### 7.3 使用规范 1. **Issue 关联**： * 每个新建的 Issue 必须尽量关联到一个里程碑。 * 未确定目标的 Issue 可先放在 “Backlog” 或 “待规划”里程碑。 2. **PR 关联**： * PR 在合并时，应确保它关联的 Issue 属于当前里程碑。 3. **进度管理**： * 里程碑进度 = 已关闭 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、完成的文档更新 | ### 8.4 使用规范 1. **任务录入** * 所有需求、Bug、改进均以 Issue 形式创建，再添加到项目中。 * 避免直接在项目中新增“空卡片”，确保信息集中在 Issue/PR。 2. **任务分配** * 项目负责人将新建 Issue 拖入 `Backlog`； * 在迭代规划时放入 `To Do` 并分配负责人； * 设置优先级标签（`high`/`medium`/`low`）。 3. **任务推进** * 开发者领取任务后，将其移至 `In Progress`； * 任务完成并合并 PR 后，移动到 `Done`。 4. **迭代关联** * 所有 `To Do` 中的任务需关联到对应里程碑； * 确保项目进度与里程碑目标保持一致。 ### 8.5 检查流程 * **每日/例会检查**：快速查看 `In Progress` 状态，排查阻塞。 * **迭代中期检查**：负责人检查里程碑完成度，必要时调整 `To Do` 范围。 * **迭代结束检查**：确认 `Done` 是否覆盖所有计划任务，遗留任务迁移到下个里程碑或保留在 `Backlog`。 ### 8.6 最佳实践 * **限制在制品（WIP）**：`In Progress` 中任务数量不宜过多，避免分散精力。 * **保持透明**：所有团队成员均应在项目中更新任务状态，避免信息滞后。 * **结合标签和里程碑**： * 标签（分类、优先级） → **任务属性** * 里程碑（版本/迭代） → **目标规划** * 项目（看板） → **执行过程** ### 8.7 角色与职责 * **项目负责人** * 创建与维护项目； * 规划任务优先级，分配负责人； * 定期检查进度并协调资源。 * **开发者** * 主动更新任务状态（拖动 Issue 卡片）； * 在 PR 中关联 Issue 和里程碑； * 按计划完成任务。 * **审查者/测试人员** * 验证任务是否符合预期； * 确认通过后推动任务进入 `Done`。 ### 8.8 项目流程图 ```mermaid flowchart LR B[Backlog
待规划任务] --> T[To Do
已排期待执行] T --> P[In Progress
正在进行] P --> D[Done
已完成] %% 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 ```