📚 Add compatibility policy to README.md

[nevans]

I saw a chart similar to this in ruby/openssl's README, and it seems like this is a relatively simple way to communicate our versioning.

I'll propose documentation for a slightly more detailed deprecation and compatibility policy... in a future PR.

[nevans]

@shugo @hsbt Does this match your understanding? Does it seem right to you?

Relevant to the top version in the table, #276 bumps the minimum ruby requirement.

[shugo]

@nevans Do you mean to maintain multiple stable branches of net-imap?

It may be enough to maintain only one branch as long as it supports all Ruby versions that are not EOL.

[nevans]

@shugo Good question.

I had assumed that we already have an implicit commitment to maintaining older versions when their matching ruby version is still in being maintained. I figured that ruby 3.1 only bundles 0.2.x, ruby 3.2 only bundles 0.3.x, etc. For example, I was thinking of the v0.2.4, and v0.3.4.1 releases back in January. That implies some commitment to maintaining those versions, right? Hypothetically, if (prior to the ruby 3.1 EOL) a serious security issue is identified with net-imap 0.2, we would probably need to create a new 0.2.x release, right? I don't think ruby wants to bundle gems with known security issues. And it would be too disruptive to bundle 0.4.x or 0.5.x in a ruby 3.1 release (upgrading from 0.2.x to 0.5.x may include backward incompatible changes).

Also, I feel that it's easier to justify adding deprecation warnings and backward incompatible changes once a year if users aren't forced to upgrade for security or critical bugfixes. Depending on the severity, backports for three older versions might even be less expensive than the alternative?

[nevans]

So my goal was to mirror ruby's branch maintenance policy: net-imap's branches would be in "normal maintenance" as long as their matching ruby branches are in "normal maintenance", and the same for "security maintenance".

This is slightly complicated by our release schedule, which is staggered from ruby's release schedule. For example, v0.4.0 through v0.4.8 were never bundled with any version of ruby (but v0.4.9 was). Because we're also releasing from main, this would give us four active release series rather than three.

[nevans]

@shugo So I guess generic proposal is this:

branch	net-imap	ruby	maintenance level
master	current	main (dev)	new features and deprecations
vx.{y-1}	current-1	current stable	"normal maintenance"
vx.{y-2}	current-2	previous stable	"normal maintenance"
vx.{y-3}	current-3	oldest stable	"security maintenance"
vx.{y-4}	current-4	end-of-life	end of life

Currently, we have:

branch	net-imap	ruby	maintenance level
master, ruby-3.3	0.4.x	3.3.x	bugfixes, deprecations
v0.3-bugfixes, ruby-3.2	0.3.x	3.2.x	backports (at our discretion)
ruby-3.1	0.2.x	3.1.x	security only
none	0.1.x	3.0.x	end of life

After bumping master to 0.5.0 and renaming some branches:

branch	net-imap	ruby	maintenance level
master	0.5.x	3.4.x	new features (and deprecations)
v0.4	0.4.x	3.3.x	bugfix backports
v0.3	0.3.x	3.2.x	bugfix backports
v0.2	0.2.x	3.1.x	security only
v0.1	0.1.x	3.0.x	end of life

However, to directly answer your question: although I'm willing to do some discretionary backports of bugfixes (maybe even small features) to the previous version, backporting bugfixes for two versions might be more than we should commit to. Maybe I should "downgrade" the last-stable-ruby's release series (currently "v0.3.x") to "security only"?

branch	net-imap	ruby	maintenance level
master	0.5.x	3.4.x	new features (and deprecations)
v0.4	0.4.x	3.3.x	backports (at our discretion)
v0.3	0.3.x	3.2.x	security only
v0.2	0.2.x	3.1.x	security only
v0.1	0.1.x	3.0.x	end of life

[shugo]

However, to directly answer your question: although I'm willing to do some discretionary backports of bugfixes (maybe even small features) to the previous version, backporting bugfixes for two versions might be more than we should commit to. Maybe I should "downgrade" the last-stable-ruby's release series (currently "v0.3.x") to "security only"?

I think it's enough.
Users can upgrade to newer versions if they are affected by normal bugs.

[zenspider]

Sharing my own painful experience... I would recommend @shugo's advice and add that being aggressive about ONLY maintaining compatibility to currently supported versions of ruby is not only sane, but necessary.

You might be better off being generic:

• current ruby = normal work
• current - 1 minor = security + backports
• current - 2 minors = security only

Aggressively dropping support for old rubies is a good thing both for maintainers and users.