snow/docs/Snow-Lang-Git-Management/Snow-Lang-Git-Management.md

Snow 项目 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 分支并通知团队，确保不影响生产环境。

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）。

• 标签命令：

  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 分支进行紧急修复，并尽快发布。