Delineating ruby gem public APIs for semantic versioning

Question

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

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.

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?

Answer 1

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

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.

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.