如何有效维护Flutter私有自定义可复用包？

一、版本控制与分支策略 #

• 采用主分支+开发分支+特性/修复分支的模式：

  • main分支：仅存放经过测试的稳定版本，每次发布新版本都打对应的语义化版本标签（比如v1.2.3），标签一旦创建不再修改，确保旧版本可追溯。
  • develop分支：用于日常开发、合并新特性，所有新功能和非紧急bug修复先提交到这里，测试通过后再合并到main。
  • bugfix/xxx或hotfix/xxx分支：针对特定版本的紧急bug修复，完成后合并到对应版本的维护分支和develop。

• 严格遵循语义化版本号规则：

  • 修订号：仅做bug修复，不改动API（v1.2.0→v1.2.1）
  • 次版本号：新增兼容现有API的功能（v1.2.1→v1.3.0）
  • 主版本号：包含不兼容的API变更（v1.3.0→v2.0.0）

二、Bug修复流程 #

1. 当前稳定版本的bug修复 #

• 从main分支切出bugfix/[bug描述]分支，完成修复后提交PR到main，合并后打新的修订版本标签（比如v1.2.2）。
• 同时将修复代码cherry-pick到develop分支，确保后续版本同步包含该修复。

2. 旧版本的bug修复 #

• 对仍有项目依赖的旧版本，提前从对应版本标签切出维护分支，比如release/v1.1.x。
• 在维护分支上完成bug修复后，打新的修订标签（v1.1.5），并通知依赖该旧版本的项目更新。
• 若修复内容适用于新版本，同样cherry-pick到develop分支。

三、旧版本管理 #

• 保留关键版本的维护分支：对于仍有项目依赖的旧主版本（比如v1.x），创建对应的release/v1.x分支，仅处理该大版本的bug修复，不再合并新功能。
• 归档过时版本：对于无项目依赖的旧版本，可在GitHub分支设置中将其标记为归档，减少分支列表混乱，但保留标签和提交记录以便后续排查。
• 维护版本清单：在包的README.md中明确标注当前支持的版本、停止维护的版本，让依赖项目清晰了解版本支持状态。

四、包的更新与依赖管理 #

1. 项目依赖私有包的方式 #

在项目pubspec.yaml中通过Git引用依赖，支持三种场景：

• 依赖特定标签（推荐稳定版本使用）：

  dependencies:
    your_package:
      git:
        url: git@github.com:your-org/your-package.git
        ref: v1.2.3
  

• 依赖维护分支（适合需要持续获取旧版本修复的场景）：

  dependencies:
    your_package:
      git:
        url: git@github.com:your-org/your-package.git
        ref: release/v1.1.x
  

• 依赖特定commit（临时调试用）：

  dependencies:
    your_package:
      git:
        url: git@github.com:your-org/your-package.git
        ref: abc1234
  

2. 通知依赖项目更新 #

• 在包仓库中创建RELEASE.md文件，每次发布新版本（包括bug修复版本）时，记录更新内容、影响范围和升级指引。
• 通过团队内部沟通渠道（如Slack、邮件）通知相关项目负责人，提醒他们根据需求升级包版本。

3. 本地开发调试 #

若需修改包并在本地项目测试，可临时使用路径依赖：

dependencies:
  your_package:
    path: ../your-package

测试完成后切换回Git引用，并提交包的代码到对应分支。

五、权限与协作管理 #

• 严格控制GitHub私有仓库权限：仅给需要维护包的开发者写入权限，依赖项目的开发者仅开放读取权限，避免误操作。
• 启用PR审批机制：所有代码变更（包括bug修复）都需通过PR提交，经至少一位其他开发者审批后再合并，确保代码质量。

内容的提问来源于stack exchange，提问作者Roy Krueger