[RFC] Semantic Versioning

[arthurschreiber]

I've been thinking a bit about changing Rugged to use Semantic Versioning.

I tried to follow the libgit2 version number in the latest Rugged releases, but that's not been working out really well. One thing that is a bit bugging me (and probably other users) is that Rugged releases are very infrequent and inconsistent, and I'd like that to change.

Now, I'd like to move to a more consistent versioning scheme and follow the guidelines of SemVer.

Here's a short rundown how I imagine this would look like:

• Development against libgit2 from git will happen in the master branch, as it does right now already. Beta releases will be cut from there and their version number will either be MINOR+1 or MAJOR+1, depending on whether newer changes break backwards compatibility or not.
• We'll keep maintaining PATCH releases for MINOR versions for as long as the matching libgit2 version receives updates.

Any comments or concerns?

[vmg]

I gave this some thought overnight. Here's a couple notes:

1. Semver is stupid -- and most people who maintain active open-source software have found this out in practice. There are a lot of good blog posts where its shortcomings are detailed, but they essentially point out that semver is too strict where it doesn't matter and too loose where it matters (e.g. most bug fixes that should be a "minor point release" are in fact breaking changes, because they change the functionality of the library).
2. I'm a huge fan of number releases. Let's pick a number, e.g. Rugged 230 to begin with, and bump that number with every release we make -- regardless of the kind of release. We usually do a release a week to add new features or wrap new stuff. So 231, 232, and so on. We don't need to think about release semantics, we simply bump the number when we want a new Rugged -- it's trivial to track in Gemfiles. We try our best not to break APIs, but if it has to be done, so be it. We add new features all the time (and fix bugs), so bumping the number always makes sense. Thoughts?

[carlosmn]

Strict adherence to the SemVer spec certainly shouldn't be the goal, but it does represent some information from the developers to the users about when something is expected to break.

I'm not sure what you mean by tracking the numbered releases in the gemfiles. Do you mean about pinning a particular release and just not making any stability guarantees between releases? The python bindings have no stability guarantees and just use the number as a guide for which libgit2 version they work against. If you link statically in rugged, you wouldn't care about this bit, but rugged is available in some distros who do want to link against the system copy of libgit2. I think there should still be some way to know against which version of libgit2 we'd be expected to run when linked dynamically.

This probably represents two quite different use-cases. Presumably GitHub and many other users don't care about linking to libgit2 and just want to get newer ruggeds. Maybe there's the possibility of two channels or a way to keep increasing numbers for the bleeding edge builds, released regularly, while letting someone say they want gem rugged, "~>0.22" or gem rugged, "~>22" and get bug fixes.

Or maybe you don't care about releasing bug fixes and can just indicate somehow that one particular releases uses a new libgit2 release.

[stim371]

:+1: for semver.

I'm coming into this issue from the perspective of a user of a gem that requires rugged. The gem has to pin rugged to a specific version, which means that, if rugged releases even a minor fix, they need to cut a whole new release. To get that fix, I now need to either pester the gem owner to cut a new patch release to bump the dependency, or fork the project and maintain that fork.