Semver, the churn of changes, and rapid deprecation

[Phrogz]

Summary of points:

• Please be very hesitant to deprecate features.
• When deprecations occur, please explain them, and explain the recommended replacement.
• When deprecation changes to removal, please note it in the release notes.
• Please use semantic versioning.

I first used Sequel…I don't even know how long ago. 18 years? Before v1.0. I love it…except:

Every N years I find myself picking up an old project, dusting it off, and bringing its libraries up to date. Sequel has been—by orders of magnitude—the most painful upgrade every time. The syntax for constructing queries keeps changing. Each change is somewhat justifiable, e.g. no more monkeypatching in Hash#~, now one must use Sequel.~(hash) just in case someone else wanted to monkeypatch their own Hash#~; Sequel::Model.<< no longer exists because it might be confusing that it returned a dataset. However, the pace and magnitude of these changes is really frustrating.

Take the two-year period from 4.24 to 4.49: there were 120 deprecations during this time. Sequel::Model.<< was deprecated in 4.48 (July 1st, 2017), changed to show a warning ("Switch to using #insert"). The release notes for it explained why, but not what one should replace it with:

Model.<< is now deprecated. Intuitivately, you would except this
to call Model.create and return the Model class, but it calls <<
on the model's dataset and returns the dataset.

One month later—31 days!!—it was removed entirely, with no further mention in the changelog or release notes. It took me 15 minutes to find CHANGELOG.old to even find a mention of this once-working feature.

I assumed that 5.0 would have breaking changes from 4.x, but did not realize that there could be (were) breaking changes in almost every 4.x release. I'm sure you all are aware of semver.org; why is Sequel using a versioning scheme that does not abide by this? If the reason is that you want to be able to make backwards-incompatible changes almost every month without the version number looking out of control, maybe that should be a sign that the practice of making so many backwards-incompatible changes is not a desirable one.

Now, things seem to be getting better. The two-year period from 5.63 to 5.87 has had only a handful of backwards-incompatible changes. But again, IMO there should be none. Certainly add deprecation warnings if you like, but (a) leave those warnings in for 3–6 months before changing the functionality, and (b) bump the major version number every single time you make a backwards-incompatible change. And perhaps consider how important it really is to make these backwards-incompatible changes. Perhaps you can save them all up.

Thank you, Jeremy (and other contributors?) for your delightful and ongoing contribution to the Ruby world. I'm complaining only because I love Sequel too much to look at another solution; I just want the relationship to hurt less. :)

[jeremyevans]

Summary of points:

• Please be very hesitant to deprecate features.

I am.

• When deprecations occur, please explain them, and explain the recommended replacement.

I do.

• When deprecation changes to removal, please note it in the release notes.

I do. In major releases, this is generally done as a blanket note. In 5.0.0, the text used was:

  All adapters, extensions, plugins, features, and constants
  deprecated in 4.49.0 have been removed.  Before upgrading to Sequel
  5.0.0, upgrade to 4.49.0 and fix all deprecation warnings.

This gives clear instructions to the user about how to handle the situation.

• Please use semantic versioning.

I do not believe strict semantic versioning makes sense for a project as large as Sequel. However, Sequel has for a very long time only broken backwards compatibility in ways that are expected to affect large numbers of users during major version bumps.

I first used Sequel…I don't even know how long ago. 18 years? Before v1.0. I love it…except:

Every N years I find myself picking up an old project, dusting it off, and bringing its libraries up to date. Sequel has been—by orders of magnitude—the most painful upgrade every time.

I'm sorry to hear that.

The syntax for constructing queries keeps changing. Each change is somewhat justifiable, e.g. no more monkeypatching in Hash#~, now one must use Sequel.~(hash) just in case someone else wanted to monkeypatch their own Hash#~;

This change was made in a major version (Sequel 4). Note that it is still supported if you use the core extensions.

Sequel::Model.<< no longer exists because it might be confusing that it returned a dataset. However, the pace and magnitude of these changes is really frustrating.

This change was made in a major version (Sequel 5). It is trivial to update to the new approach by switching to insert, as mentioned in the deprecation warnings.

Take the two-year period from 4.24 to 4.49: there were 120 deprecations during this time.

Which of these deprecations affected you, other than the ones you mentioned?

Sequel::Model.<< was deprecated in 4.48 (July 1st, 2017), changed to show a warning ("Switch to using #insert"). The release notes for it explained why, but not what one should replace it with:

Model.<< is now deprecated. Intuitivately, you would except this
to call Model.create and return the Model class, but it calls <<
on the model's dataset and returns the dataset.

The deprecation warning did explain what you should replace it with, and if you followed the instructions in the release notes, and ran with Sequel 4.49.0, and you were one of the few users using Model.<< , then you would have seen the deprecation warning.

One month later—31 days!!—it was removed entirely, with no further mention in the changelog or release notes. It took me 15 minutes to find CHANGELOG.old to even find a mention of this once-working feature.

As mentioned above, it was removed in a major version. If the instructions in the 5.0.0 release notes had been followed, the deprecation notice with the instructions for replacement would have been seen, and you could fix the issue before upgrading to Sequel 5.

I assumed that 5.0 would have breaking changes from 4.x, but did not realize that there could be (were) breaking changes in almost every 4.x release.

I don't think there were significant breaking changes in almost every 4.x release, and I would guess that most users did not have any breaking changes in a 4.x point release. Can you please list any breaking changes in a 4.x release other than 4.0 that affected your applications?

I'm sure you all are aware of semver.org; why is Sequel using a versioning scheme that does not abide by this?

Because semver was designed for small libraries, where any change of any function in the library is likely to affect a large number of the library's users. It is not designed (or at least it is very poorly designed) to handle large libraries. Not all backwards incompatible changes are of equal effect, yet semver wants the library developer to treat them all as if there are of equal effect.

If the reason is that you want to be able to make backwards-incompatible changes almost every month without the version number looking out of control, maybe that should be a sign that the practice of making so many backwards-incompatible changes is not a desirable one.

There are not backwards incompatible changes that affect a significant number of Sequel's users every month. In the cases where backwards incompatible changes are made outside major versions, they are usually very minor and unlikely to affect more than a small fraction of Sequel's users.

Now, things seem to be getting better. The two-year period from 5.63 to 5.87 has had only a handful of backwards-incompatible changes. But again, IMO there should be none.

Can you list which of the backwards-incompatible changes affected you in the Sequel 5 series? I don't think it makes sense to discuss further back than that, since Sequel 5.0 was more than 7 years ago.

Certainly add deprecation warnings if you like, but (a) leave those warnings in for 3–6 months before changing the functionality, and (b) bump the major version number every single time you make a backwards-incompatible change. And perhaps consider how important it really is to make these backwards-incompatible changes. Perhaps you can save them all up.

Backwards-incompatible changes that affect a significant number of users are saved up until the next major version. You can already see that by looking for existing deprecation warnings in Sequel, which discuss backwards incompatible changes to be made in Sequel 6.

Thank you, Jeremy (and other contributors?) for your delightful and ongoing contribution to the Ruby world. I'm complaining only because I love Sequel too much to look at another solution; I just want the relationship to hurt less. :)

I am sorry that you've had a bad experience in the past. Maintaining a large library is a series of tradeoffs, and I am very considerate of backwards compatibility issues, but sometimes progress requires breaking backwards compatibility.

Are you aware of any other Ruby database abstraction library with a better track record than Sequel's in regards to backwards compatibility?