diff --git a/README.md b/README.md index 0d60b90..3b1023e 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,8 @@ * 每次提交必须包括清晰、简洁且具描述性的提交信息,确保团队成员能够轻松理解变更的目的和内容。 * 严禁直接在 `main` 分支上进行开发。所有功能开发必须通过独立分支进行。 +--- + ## 2. 分支管理 本项目采用以下分支策略进行代码管理: @@ -65,92 +67,7 @@ 5. 将修复后的变更合并回 `dev` 分支,确保所有的修复和调整同步到开发分支,防止后续开发中出现同样的问题。 6. **回滚策略**: 如果热修复未能解决问题,立即回滚合并,删除 `hotfix` 分支并通知团队,确保不影响生产环境。 -## 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 拉取请求流程 - -1. 开发者在完成功能或修复后,创建 PR,将其分支合并至 `dev` 或 `main` 分支。 -2. 其他团队成员进行代码审查,重点检查代码质量、功能完整性及测试覆盖率。 -3. 审查通过后,PR 将被合并。 - -### 4.2 代码审查 - -* 所有 PR 必须经过至少一名开发者的代码审查。 -* 审查时应关注以下方面: - - * 代码是否符合项目的编码规范。 - * 是否提供了足够的单元测试覆盖。 - * 是否存在冗余代码或复杂度过高的部分。 - * 功能是否按预期工作。 - * 审查者应在 PR 中提供反馈,确保代码质量高,符合团队要求。 - -## 5. 版本发布 - -版本发布基于 Git 标签,发布流程如下: - -### 5.1 打标签 - -每当版本准备发布时,应在 `main` 分支上打上版本标签: - -* **版本号规则**: 采用语义化版本控制(SemVer)格式,版本号由三部分组成: `主版本号.次版本号.修订号`(例如: `v1.0.0`)。 -* **标签命令**: - - ```bash - git tag v1.0.0 - git push origin v1.0.0 - ``` - -### 5.2 发布流程 - -1. 确保所有功能已合并至 `dev` 分支,并通过集成测试。 -2. 从 `dev` 分支创建 `release` 分支,进行版本发布的准备工作。 -3. 在 `release` 分支上完成最终修改,如文档更新和版本号调整。 -4. 将 `release` 分支合并至 `main` 并打上版本标签。 -5. 将 `release` 分支的变更合并回 `dev`,确保所有修复和改动在开发分支中得到同步。 - -### 5.3 发布后 - -* 发布版本后,团队成员应确保将 `main` 分支的最新代码拉取到本地,以保持代码库的同步。 -* 如出现生产环境问题,应及时创建 `hotfix` 分支进行紧急修复,并尽快发布。 - +### 2.7 分支流程图 ```mermaid flowchart LR @@ -189,22 +106,124 @@ flowchart LR class F,B branch; class H hot; class P env; - - ``` -### 简要说明 +#### 简要说明 * **主流程**:所有开发都在 `feature/` 或 `bugfix/` 分支,合并至 `dev`,再经过 `release/` 到 `main`。 * **发布**:`release/` 分支只用于准备发布,合并后要打 Tag 并同步回 `dev`。 * **热修复**:`hotfix/` 从 `main` 分支拉出,紧急修复后要同时同步回 `main` 和 `dev`。 -* **所有分支** 推荐通过 **PR(拉取请求)** 合并,需经过代码审查。 +* **所有分支** 通过 **PR(拉取请求)** 合并,需经过代码审查。 -## 6. Issue 管理规范 -### 6.1 Issue 基础 +## 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 拉取请求流程 + +1. 开发者在完成功能或修复后,创建 PR,将其分支合并至 `dev` 或 `main` 分支。 +2. 其他团队成员进行代码审查,重点检查代码质量、功能完整性及测试覆盖率。 +3. 审查通过后,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`。 + +* **标签命令**: + + ```bash + git tag v1.0.0 + git push origin v1.0.0 + ``` + +* **注意事项**: + + * 所有版本标签必须基于 `main` 分支最新的稳定提交。 + + +### 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 报告以及改进建议。 @@ -216,27 +235,24 @@ flowchart LR * 在提交 PR 时,应在描述中关联对应的 Issue(如 `close #123` 或 `resolve #123`)。 * Issue 状态应及时更新,避免长期挂起。 ---- ### 6.2 Issue 分类 -为保证管理清晰,建议使用以下标签(Label)对 Issue 分类: +| 标签名 | 说明 | 用途举例 | +| --------------- | ---------- | ----------- | +| **类型标签** | | | +| `bug` | 缺陷或错误修复 | 修复功能异常、错误行为 | +| `feature` | 新功能开发 | 开发新模块、新接口 | +| `enhancement` | 功能改进或优化 | 性能优化、界面优化 | +| `documentation` | 文档相关 | 修改/补充文档 | +| `test` | 测试相关 | 单元测试、集成测试 | +| `question` | 需要进一步澄清 | 提问、需求澄清 | +| `wontfix` | 不会修复 | 不予处理的问题 | +| **优先级标签** | | | +| `high` | 高优先级,需立即处理 | 紧急缺陷、重大阻塞 | +| `medium` | 中等优先级,近期处理 | 普通功能需求 | +| `low` | 低优先级,长期计划 | 次要改进、未来规划 | -* **类型标签**: - - * `bug`: 缺陷或错误修复 - * `feature`: 新功能开发 - * `enhancement`: 功能改进或优化 - * `docs`: 文档相关 - * `discussion`: 需要团队讨论的主题 - -* **优先级标签**: - - * `priority: high`(高优先级,需立即处理) - * `priority: medium`(中优先级,近期处理) - * `priority: low`(低优先级,长期计划) - ---- ### 6.3 Issue 流程 @@ -257,14 +273,211 @@ flowchart LR 4. **关闭 Issue** - * 当 PR 合并后,相关 Issue 自动关闭。 + * 合并 PR 前需要关闭关联 Issue。 * 如果问题未解决,应重新打开或创建新的 Issue。 ---- - ### 6.4 Issue 最佳实践 * **描述清晰**:避免模糊描述,如“修复报错”;应写明“修复用户登录时因 token 校验失败导致的 500 错误”。 * **一个 Issue 只包含一个问题**:避免一个 Issue 同时涉及多个 Bug 或功能需求。 * **保持更新**:在处理过程中,及时补充进展,方便团队成员了解状态。 -* **结合 Milestone**:将 Issue 归档到迭代或版本里,保证任务有明确的交付目标。 \ No newline at end of file +* **结合 Milestone**:将 Issue 归档到迭代或版本里,保证任务有明确的交付目标。 +--- + + +## 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、完成的文档更新 | + +> 团队可在必要时新增列,例如 `Blocked`、`QA`,但推荐保持简洁。 + + +### 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 +``` \ No newline at end of file