branching.md

分支管理规范

本文档定义 ECOS Embedded SDK 的长期分支结构、命名规则与合并策略。

1. 目标

本仓库后续采用“版本分支 + 产品分支 + 短期功能分支”的管理方式，避免将版本演进、板卡产品适配和临时开发工作混在一起。

2. 长期分支

2.1 版本分支

• 1.0

  • 对应 v1.0.0 时代的稳定版本线。
  • 仅接收 1.x 系列的缺陷修复、文档修正和必要的兼容性更新。

• 2.0

  • 对应当前 2.0 版本的主开发线。
  • 新功能、架构升级、HAL 演进和当前主版本维护默认进入该分支。

2.2 产品分支

• starryskypi
  • 用于继续维护 StarrySkyPi 相关适配。
  • 该分支是产品线，不替代版本主线。
  • 若某项能力先在 2.0 完成并且 StarrySkyPi 需要复用，应从 2.0 选择性合并，而不是长期直接混合开发。

3. 分支职责

• main

  • 仅作为默认展示入口或对外聚合入口使用。
  • 不再承担日常开发分支职责。
  • 是否继续保留为默认分支，可在远端平台按发布策略决定。

• 1.0

  • 稳定维护分支。
  • 不接受 2.0 的破坏性变更。

• 2.0

  • 当前主开发分支。
  • 所有与 2.0 相关的日常开发、集成和回归应在该分支完成。

• starryskypi

  • 产品定制分支。
  • 仅接收 StarrySkyPi 专属改动，以及经确认需要同步的上游改动。

4. 功能分支命名

所有临时开发分支都应从长期分支切出，并在合并完成后删除。

推荐命名：

• feature/2.0/<topic>
• fix/2.0/<topic>
• feature/starryskypi/<topic>
• fix/1.0/<topic>

示例：

• feature/2.0/l3_1-uart
• fix/1.0/install-script
• feature/starryskypi/gpio-test

5. 合并规则

• 1.0

  • 只合并经过验证的修复。
  • 禁止将 2.0 整体回灌到 1.0。

• 2.0

  • 接收 2.0 的功能开发与问题修复。
  • 允许将已完成的短期功能分支合并回 2.0。

• starryskypi

  • 需要同步 2.0 能力时，采用明确范围的 merge 或 cherry-pick。
  • 不建议长期大量偏离后再一次性回合并。

6. 发布建议

• 1.0.x 标签从 1.0 分支打出
• 2.0.x 标签从 2.0 分支打出
• starryskypi 如需独立交付，可单独打产品标签，例如：
  • starryskypi-v2.0.0
  • starryskypi-v2.0.1

7. 当前整理结果

当前建议的本地长期分支为：

• 1.0
• 2.0
• starryskypi

历史上名为 dev2.0 的开发线，应逐步迁移为 2.0。