【发布时间】：2020-03-27 21:52:12
【问题描述】：
目前，我对 API 使用语义版本控制。
版本控制是这样的：
进行不兼容的 API 更改时的主要版本
以向后兼容的方式添加功能时的次要版本
进行向后兼容的错误修复时的 PATCH 版本
如果我只更新文档（swagger、内部文档、YAML 等）以添加示例，或者更正附加到 API 的说明，是否应该增加 PATCH？
感谢您的帮助；）
【问题讨论】：
【发布时间】：2020-03-27 21:52:12
【问题描述】：
如果我只更新文档（swagger、内部文档、YAML 等）以添加示例，或者更正附加到 API 的说明，我应该增加 PATCH 吗？
取决于示例/更正。它是否代表了与之前对 API 使用的理解的突破？这是一个非常人为的讨论示例：
API：int plus(int a, int b)
文档：int plus(int a, int b) sums a + b.
上面是作为1.0.0发布的，然后有人查看代码并指出溢出时，函数返回0。
更新的文档：int plus(int a, int b) sums a + b where a < 32767 and b < 32767, otherwise, returns 0.
因此，这是否是一项重大更改，取决于 a + b 溢出时的语言及其行为。有些语言会抛出异常或段错误，而另一些语言通常会简单地返回某种模数结果。假设它是 C，在这种情况下，此文档更改可能是一个重大更改（嗯，实际上可能是大多数编程语言）。
这里的重点是，最初的文档通常并不比 API 本身的表面重述好多少。当客户对结果感到惊讶时，来自客户的后续投诉（错误报告）通常会推动下一轮文档更改。所以是的，即使开发人员的初衷没有改变，但文档确实代表了对预期结果的重大改变。
如果更改了文档以完全符合客户在使用中的期望/见证，那么不，这不是重大更改。
文档是功能集的一部分。回填缺少的文档通常是一个特性添加，所以你会碰到次要版本。一个小的修正将是一个补丁。
【讨论】：