Add "Versioning Policy" page

[solnic]

We should establish an official versioning policy that dry-rb follows:

SemVer

• Patch release - should not break things, only bug fixes / minor improvements
• Minor release - same as Patch + introduces new features or improvements in existing features
• Major release - same as Patch + Minor but it may change public API

Ruby Support

• Every dry-rb gems supports all versions of Ruby that are supported by the Ruby Core Team
• required_ruby_version in gemspecs can be changed only in Minor or Major releases
• We can consider re-adding support for a deprecated Ruby version based on community feedback and support

[nevans]

FWIW, I didn't know about this ticket at the time, but I found this commit dry-rb/template-gem@f39d392 after dry-initializer wouldn't upgrade for a project that still needs to run on 2.6 (which is still supported by the Ruby Core Team). I left my thoughts on that commit.

I think the only thing I'd want changed in your policy as stated above: breaking changes to dependencies are transitive (IMO). Especially when those transitive dependencies are likely to also be direct dependencies (which will always be the case for the language itself). And (like most big projects) ruby doesn't follow SemVer, so minor releases will contain breaking changes. Therefore: updating required_ruby_version to a higher minor version (i.e. 2.6 to 2.7) is a breaking change. Under SemVer that can only be done with a major release.

Personally, I have issues with SemVer and I think its 100% fine if you deviate on this detail. But if so: please document that in the "SemVer" section of the documentation (in addition to the "Ruby Support" section)... for those of us who sometimes skim through dozens of gems' documentation, and thus suffer from reduced reading comprehension. 😉

[solnic]

@nevans thanks for your feedback. I agree that dropping support for a given ruby version should only take place with a major version bump. I'd like to re-think this because I can easily see how this can cause issues. We also released dry-auto_inject which now requires 2.7.0 but this gem is still below 1.0 so in this case I think it's fine. For any stable gem, including other gems that depend on it (ie rom depends on dry-initializer) we should only drop ruby support in a major bump (so in rom would be bumped to 6.0 because dry-initializer would be bumped to 4.0 and both releases would drop ruby 2.6).

@flash-gordon @jodosha @timriley WDYT about this approach?

[flash-gordon]

I can easily see how this can cause issues

Well, I don't. How come not being to use the latest version is a breaking change?
On the other hand, I would argue your suggested approach puts a lot more work on all parties.

We maintain many gems with different release schedules. If we to release a major update to, say, dry-core or dry-types it'll trigger a wave of subsequent releases, in the end, most of them likely will be technical. Otherwise, we would have to test all gems against previous versions of dependencies. On each major bump, we'll be deciding what features to keep and what to drop, users will have trouble understanding which changes are really breaking. Also jumping through changelogs of all dependencies would be quite time-consuming (most users won't do this ofc).

The alternative is to support all ruby versions for all gems. This clearly puts more pressure on maintainers and complicates contributions, now all commiters have to deal with the fact there're obsolete versions of ruby. Easily, there can be problems with installation etc. There will be problems with using new language features. Those that syntactially-compatible can be used with RUBY_VERSION checks at the expense of duplicated code. The more checks we have the harder it gets to maintain them. Things are worse with syntax updates, they can only be used with evals which makes code a lot harder to understand. On the other hand, not using new features puts users with recent ruby versions (me included) at disadvantage, newer features usually speed things up or make code easier to read (arguably but anyway).

Some gems, such as i18n keep backward compatibility and bump the required ruby version from time to time without bumping the major version. I find this approach if not ideal then optimal. By any means, I don't consider an inability to use new lib features on an older ruby version a breaking change.

Probably, there's an important distinction between low-level libs like dry-types and high-level ones/frameworks like dry-system, rom, hanami. It's quite possible we can have two different policies for them.