tommwq.work/aip

AIP-3 AIP版本控制

· [tommwq@126.com]
编号 3
原文链接 https://google.aip.dev/3
状态 批准
创建日期 2023-03-28
更新日期 2023-03-28

本AIP定义了AIP版本控制方案。

指南

  • AIP集合 必须 使用日期进行版本控制,采用ISO-8601的YYYY-MM-DD格式,对应于版本创建日期。
  • AIP版本 必须 在存储AIP的源代码控制系统中以标签形式提供,格式为 v{version} 。例如: v2023-03-28
  • 如果一个或多个AIP发生重大变化, 必须 为AIP集合创建新版本。
  • 每个AIP 必须 包含修订记录部分,记录修订日期和修订内容。

原理

版本可以作为AIP在特定时间点的参考依据。AIP指南可能被撤销,或者发生重大变化,以至于和原始设计相差甚远,因此版本非常重要,。遵循AIP的API可能需要引用旧版AIP指南,来证明设计方案在当时是合理性的。

基于日期的版本控制原理

使用基于日期的版本控制,API使用者很容易找到创建API时实施的AIP指南。

为什么不对每个AIP进行单独的版本控制

对每个AIP进行独立的版本控制,是全局版本控制的备选方案。

AIP经常相互引用。如果每个AIP都有多个版本,引用时也必须指定目标AIP版本,才能提供完整的指南。