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

Question

语义版本控制规范中的第一点指出兼容软件必须声明公共API.

我想知道宝石是如何建立这个公共API的.看起来它通常是通过自述文件完成的(例如,参见ActiveRecord),它不觉得它在公共API代码和其他代码之间划出了严格的界限.更好地执行此操作的gem的一个示例是Twitter API,将其公共API代码放在API目录中,但即使在那里,该行也是灰色的,因为公共API的configure方法在API目录之外的twitter.rb中定义.

作为一个试图坚持语义版本控制的宝石的潜在贡献者(这是他们中的大多数,因为我们有像bundler这样的工具),我想知道哪些方法是公共API的一部分,哪些不是.也许我必须查看更多的源代码,但有没有明确定义您的公共API的指导方针？

Answer 1

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

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

另一种方法是测试.我认为Merb做到了这一点.公共API在其RSpec测试中有所描述.私有部分显然也经过了测试,但这些测试都存在于不同的目录中.

这实际上非常酷,因为它允许您将代码更改和语义版本更改联系在一起:每次向公共目录添加测试时,都需要碰撞次要版本.每次删除或修改公共目录中的测试时,都需要修改主要版本.

或者反过来说:在次要修订期间,不允许更改或删除测试.