描绘用于语义版本控制的ruby gem公共API [英] Delineating ruby gem public APIs for semantic versioning

问题描述

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

The first point in the Semantic Versioning Specification states that compatible software must declare a public API.

我想知道gem如何建立这个公共API.似乎通常是通过自述文件完成的(例如，请参见 ActiveRecord )，这似乎并没有在公共API代码和其他API之间划出严格的界限. Twitter API 就是一个做得更好的gem的示例，将其公共API代码放在 API目录，但即使在那一行也是灰色的，因为公共API的配置方法在API目录外部的 twitter.rb 中定义

I'm wondering how gems establish this public API. It seems that it's typically done through the readme (see ActiveRecord, for example), which doesn't feel like it draws a strict boundary between the public API code and the rest. An example of a gem that does this better is the Twitter API, placing its public API code in an API directory, but even there the line is grey, as the public API's configure method is defined in twitter.rb, outside the API directory.

作为试图坚持语义版本控制的gem的潜在贡献者(考虑到我们拥有捆绑器之类的工具，大多数尝试这样做)，我想知道哪些方法是公共API的一部分，哪些不是没错也许我必须浏览更多的源代码，但是在某处有明确定义公共API的准则吗?

As a potential contributor to a gem that attempts to stick to semantic versioning (which is most of them, given we have tools like bundler), I'd like to know which methods are part of the public API, and which aren't. Maybe I have to look through more source code, but are there guidelines somewhere for clearly defining your public API?

推荐答案

有一些流行的方法来定义公共API.您选择哪一个主要取决于口味.

There are some popular ways to define the public API. Which one you choose is mostly a matter of taste.

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

One way is documentation. You simply state in the documentation, which protocols are part of the public API, and what the contract of those protocols is. YARD even has predefined tags for this.

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

Another way is testing. I think Merb did this. The public API was described in its RSpec tests. The private parts were obviously also tested, but those tests lived in a different directory.

这实际上很酷，因为它使您可以将代码更改和语义版本更改结合在一起:每次将测试添加到公共目录时，都需要更改次要版本.每次在公共目录中删除或修改测试时，都需要更改主要版本.

This is actually pretty cool, because it allows you to tie together code changes and semantic version changes: everytime you add a test to the public directory you need to bump the minor version. Everytime you delete or modify a test in the public directory you need to bump the major version.

反之亦然:在次要修订版本中，您不得更改或删除测试.

Or the other way round: you are not allowed to change or delete tests during a minor revision.

这篇关于描绘用于语义版本控制的ruby gem公共API的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！