5

In an open source framework deprecated APIs were removed during the beta phase on the road to a new major version. Now users request to restore some deprecated APIs because it breaks compatibility. For me, beta stands for "Use at your own risk".

  • Isn't it expected that due to a major version bump the API may change?
  • Is it "uncommon" to change the API in a beta phase?
  • API changes is not identical to backwards-incompatible API changes, as in your title. – SOFe Jul 7 '16 at 7:44
  • 5
    In theory you're right. In practice, it doesn't really matter how you label the software. It matters if you're in a position to ignore users demanding backwards compatibility. Especially since a lot of software is labeled "beta" for years. – CodesInChaos Jul 7 '16 at 7:56
  • 1
    A major version bump should be a signal that APIs might change. (It might even signal that the implementation language has changed.) However, to be nice to the users of your package, it would perhaps have been better to have published those non-backwards compatible changes in an alpha release. If you did do that, then shame on your users. If you had published plans to make non-backwards compatible changes in the upcoming release and no one responded, that too would be a shame on your users. But springing it unannounced: That might well be shame on you. (You did not say which is the case.) – David Hammen Jul 7 '16 at 14:04
  • Did you remove API calls that were deprecated in the production version of the code, or that you introduced in the alpha/beta phase of the new code? – TMN Jul 7 '16 at 19:18
5

As you have mentioned, your users are currently complaining on the road to a new major version.

Isn't it expected that due to a major version bump the API may change?

Either you don't make backwards-incompatible changes in the API, or you would be doing that in a major version bump. If you aren't doing it in a major version bump, where would you be doing that? Unless you do it in a minor version bump, which is obviously even more improper. So basically, there is nowhere better to do it apart from a major version bump, right?

API changes are or are not expected in a major version change, depending on your system of API versioning. It seems that in your case, it is. This is your own decision, although common. Unless you are totally not planning to make backwards-incompatible changes.

Is it "uncommon" to change the API in a beta phase?

The beta phase, according to the usage specified in your post, can be assumed as "previews of a release candidate", and "not finalized". If you are having backwards-incompatible changes, you should release them as soon as possible in order to give more time to the users of your API, say, to fix the compatibility problems. Of course, you won't do that in releases before the version bump because of obvious reasons (you have already marked @Deprecated in earlier versions! Why did people still compile code despite the warnings?). Since you are going to make these changes in the release candidate anyway, why leave them later? Moreover, technically your beta versions are already major-version-bumped.

This question can also be understood as API changes betwteen beta releases of the same version. As long as you are going to add these changes in the major version bump, it is not a problem. After all, during the beta phase, the API changes can be considered as "not yet finished changing".

Finally, always remember: every single change breaks backwards compatibility.

xkcd: Workflow -- There are probably children out there holding down spacebar to stay warm in the winter! YOUR UPDATE MURDERS CHILDREN.

  • Very good, except for the Finally, always remember: every single change breaks backwards compatibility. That's not necessarily true. A change that adds functionality without changing any existing functionality (including bug fixes) does not break backwards compatibility. API changes obviously break backwards compatibility. Not so obviously, bug fixes can break backwards compatibility. Someone else's code may be relying on or taking advantage of that buggy behavior. – David Hammen Jul 7 '16 at 13:59
  • @DavidHammen that's a joke referring to the xkcd comic. The main point was to never worry too much about users' complaints on backwards compatibility, because every change can break compatibility somehow and most of the time it's users' fault. Say, who told you to use reflections to scan all methods in that class and call them one by one, now that you are crashing because of the addition of a private method that isn't even exposed to the API at all? – SOFe Jul 7 '16 at 15:09
  • Note: I have a strong feeling regarding this issue because of my experience from PocketMine, which has a plugin API, and <primarily-opinion-based>kids use seriously discouraged ways all the time to get things done (so as to get fame on the community ASAP), usually neglecting the fact that they may not work at all, and then blame the software for everything.</primarily-opinion-based> This should not be the case if there are more mature users. – SOFe Jul 7 '16 at 15:13
  • 1
    Adults also do that. Bjarne Stroustrup did not like introspection. He disliked it so much he intentionally omitted it from C++. I suspect he was a bit horrified when people discovered they could use C++ templates in a rather kludgy way (SFINAE) to do some amount of introspection. – David Hammen Jul 7 '16 at 15:34
6

To cite from Semantic Versioning 2.0.0

Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

Hence, if you talking of a beta as the 0.x.x version then yes. Anyway, considering section 8

Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API.

and section 10

A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version.

If you are talking of a beta as an unstable version of a new release, a non backward-compatible change in the public API would be 'legal' if you increased the major version, but not afterwards.

I believe that many projects use semantic versioning or a similar versioning scheme. Anyway, anything said does only hold true for semantic versioning. If you are following your own versioning scheme you are free to do anything you like, but if you keep breaking the public API people using you library could get frustrated and stop using it, so you should consider keeping all changes in a development branch and only release a beta of a new version if you are sure that there won't be any more changes in the public API.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.