My Dilemma Of Semantic Versioning

{{{
Hello. I am a gem author and I got a problem. It’s called versioning.

Yes, you’re right. _Versioning_. It’s the third big problem of computer science, after expiring caches and naming things.

My gems are all under active development. For some strange reasons, I am avoiding _major_ releases as people might be expecting a _major_ new break-through feature, but all I changed was a _minor_ detail that will affect 1% of all users.

I do minor version bumps instead and try to deprecate as much as possible. Apparently, this is not enough as there’s always angry users with broken builds that “didn’t expect that change with a minor release”.

h3. What Is Semantic Versioning?

The idea of “semantic versioning”:http://semver.org/ is very clever, and I’m happy there’s something close to a standard.

A semantic version is a string like @1.0.3@, the three segments are called major, minor and patch version. You increment major when you made an “incompatible change”, meaning that the new gem version might break your old code. The minor is bumped when the change is “backward-compatible”, so your code is guaranteed to work with the updated gem. Patch is used when incorporating bug fixes and feature additions.

h3. Semantic Versioning And Gems.

The problem arises when you’re actively working on your gems – which I happen to do! Actively in terms of adding features, fixing bugs _and_ *constantly refactoring* older parts of code. When I refactor stuff I often find better, cleaner ways to achieve something and not uncommonly the restructuring comes with a “minor” behaviour change of the code.

Here are two examples to illustrate my dilemma.

A while ago I started moving common code I use in all my gems into the “uber”:https://github.com/apotonick/uber gem. For instance, in representable I allow “dynamic options”.

property :title, if: Rails.env == "production"
property :title, if: lambda { policy.ok? }

That’s a common pattern found in many gems. The @:if@ (or any other option) allows providing a string, a lambda, a symbol, etc and evaluates that at run-time.

Evaluating those options is now handled by uber – which saves me a lot of work. In uber, a dynamic option lambda _always_ receives arguments (at this point it is totally irrelevant what options).

h3. Breaking Things.

So, after updating from representable 1.7.8 to 1.8.0, the above code would break as the old code does _not_ accept arguments.

The fix is to change code as follows.

property :title, if: lambda { |*| policy.ok? }

It’s a really really simple fix. It basically says “I know there might be options passed into my block but I don’t care”.

I didn’t deprecate the former behaviour, but that’s another issue. I knew this was gonna break “some” people’s code. I announced that in the “CHANGES”:https://github.com/apotonick/representable/blob/master/CHANGES.md#major-breakage, blogged about it, and supported wherever I could.

I didn’t deprecate it as the new solution is way cleaner and consistent – all options receive arguments, are evaluated using the same mechanism, and so on.

Not deprecating this change was stupid. However, deprecating things is pain and not every development team has a horde of willing programmers as in Rails core to work on deprecations.

Most users just updated their @:if@ blocks to receive args and moved on. Some users complained – legitimately – that they were expecting a major bump.

h3. Minor Details.

Another example, also in representable, is when I changed the way inline representers are created. This is a completely internal change.

class SongRepresenter < Representable::Decorator
  property :title
  property :label do
    property :manager
  end
end

Again, the details here are irrelevant. Look at that block.

property do .. end

That’s what we call an “inline representer”. What happens behind the scenes is a new decorator class gets created for that nested block.

Until today, that new class was inherited from @SongRepresenter@. This is wrong as this might lead to unexpected behaviour in the inline representer. In the new version, that new decorator would be derived from @Representable::Decorator@.

And, right – that change is so _internal_ that 99% of the users won’t even notice that change because nothing changes or breaks for them.

However, 1% of your users, I call them _”power users”_, do amazing stuff with your gem – stuff you didn’t even think of when designing the framework.

Their code might break with that update. They will complain and I have to lower my head in shame and admit that I didn’t properly version my shit.

What makes me frustrated here is that you simply _cannot_ deprecate it – there’s no way to find out if a users relies on the old superclass for the inline representer. It’s a dilemma.

h3. Semantic Versioning – Done Right.

The solution I suggest is to add a fourth segment to the semantic version and shift its meanings down one level. That would mean @1.2.0.1@ to @1.3.0.0@ is not backward-compatible. I find this a stupid idea and I know you hate it, too.

That’s why the only way to keep my beloved users happy is to do semantic versioning right. I have to consistently release major versions whenever I change behaviour without deprecating it.

This would lead to fast growing major numbers, e.g. @14.1.0@ or something like that. I am not sure about the acceptance in the Ruby community for that.

To me, it feels strange to see those version numbers. Others, like my friend Ricardo, “find it totally ok”:https://twitter.com/locks/status/483383889059385344. Ryan “refers to Chrome”:https://twitter.com/ryanbigg/status/483382039630999552 which is currently at v35.

It appears that semantic versioning was designed to have big major numbers – how would you follow an innovative path for development otherwise?

What’s your thought on that? Fast growing majors? Catch-all deprecations? No changes at all???