描述语义版本化的红宝石公共API

Question

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

我想知道如何建立这个公共API的宝石。它似乎通常是通过自述文件完成的（例如，参见ActiveRecord），它并不觉得它在公共API代码和其他代码之间绘制了严格的界限。更好的做法是使用​​，其公开API代码为API directory，但即使在那里，该行也是灰色的，因为公共API的配置方法在API目录之外的twitter.rb中定义。

作为试图坚持语义版本控制（这是其中大多数，因为我们有像捆绑软件的工具）的宝石的潜在贡献者，我想知道哪些方法是公共API的一部分，哪些不是。也许我需要查看更多的源代码，但是有没有指导方针可以清楚地定义您的公共API？

Answer 1

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

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

另一种方式是测试。我想Merb是这么做的。公共API在其RSpec测试中进行了描述。私密部分显然也进行了测试，但这些测试居住在不同的目录中。

这实际上非常酷，因为它允许您将代码更改和语义版本更改绑定在一起：每次向公共目录添加测试时，都需要对次版本进行修改。每次在公共目录中删除或修改测试时，都需要修改主要版本。

或者反过来：在次要版本中不允许更改或删除测试。