描述用于语义版本控制的 ruby​​ gem 公共 API

Question

Semantic Versioning Specification 中的第一点声明兼容软件必须声明公共 API。

我想知道 gems 是如何建立这个公共 API 的。似乎它通常是通过自述文件完成的（例如，参见 ActiveRecord），这并不像是在公共 API 代码和其他代码之间划定了严格的界限。一个更好的 gem 示例是 Twitter API，将其公共 API 代码放在 API directory 中，但即使在那里，这条线也是灰色的，因为公共 API 的配置方法在 API 之外的 twitter.rb 中定义目录。

作为尝试坚持语义版本控制的 gem 的潜在贡献者（这是其中的大多数，因为我们有 bundler 之类的工具），我想知道哪些方法是公共 API 的一部分，哪些是不。也许我必须查看更多源代码，但是否有明确定义公共 API 的指南？

Answer 1

有一些流行的方法来定义公共 API。你选择哪一个主要是一个品味问题。

一种方法是文档。您只需在文档中说明哪些协议是公共 API 的一部分，以及这些协议的合同是什么。 YARD 甚至为此预先定义了标签。

另一种方法是测试。我认为 Merb 做到了这一点。公共 API 在其 RSpec 测试中进行了描述。私密部分显然也经过了测试，但这些测试位于不同的目录中。

这实际上很酷，因为它允许您将代码更改和语义版本更改联系在一起：每次向公共目录添加测试时，您都需要修改次要版本。每次删除或修改公共目录中的测试时，都需要升级主要版本。

反之亦然：在次要修订期间，您不得更改或删除测试。