Change in behavior

[tallesl]

The spec is well defined when it comes to changing the API, take the following paragraph for instance:

Bug fixes not affecting the API increment the patch version, backwards compatible API additions/changes increment the minor version, and backwards incompatible API changes increment the major version.

Pretty straightforward.

But what about substantial behavioral changes? There are times that you make big changes in a code behavior without changing a thing on its API. Is that a patch?

Example 1

Suppose there's a library that sends emails. Let's say that on version 1.0.0 it simply sends emails as plain text, no configuration there.

On its second release the author changes the library to send emails as HTML instead, without changing anything on its API. It does that automatically. What's the version?

For the user that rely on the fact that it sends only plain text emails, that's a major (2.0.0). For the user that may be interested in sending emails with rich content now and doesn't bother with HTML being automatically assumed, that's a minor (1.1.0). For the user that expects semver to be solely about the API as the spec mentions it, that's a patch (1.0.1).

Example 2

Imagine a scheduling library for an object oriented language that accepts custom jobs designed by a user. The user gives the library the type of its job implementation and some cron-like scheduling.

On current version the library instantiates one single job object and calls it (the same object) every time its schedule is fired.

Now someone points out the fact that may be a better design to instantiate a new object for each time the scheduled is fired. The author of the library finds the argument convincing and changes the library, but no API change was needed.

If one uses the library only with stateless jobs that's a patch alright. But what if some of the library users were relying on the fact that it treated the jobs as singletons?

(this last example is a real scenario by the way)

[haacked]

The behavior of an API is part of the API, not just the shape of the API. So in Example 1, I'd consider that a breaking change and increment the major version. Another way to look at it is that SemVer is about communicating intent and risk of breaking to consumers. If a large number of customers would consider it a breaking change, then you could increment the major.

For example, in Example 1, instead of replacing text with HTML, you used multi-part mime type to send an email as both, you could argue that's just a minor increment because existing emails continue to work as before and only those who opt-in to the HTML get HTML.

For example 2, I'd argue that it depends on whether the singleton behavior is explicitly called out as part of the design of the API. It seems to me that people are relying on an implementation detail if they assume the singleton. So I would not increment major unless I had strong data to indicate that changing this behavior would break a large number of my customers.

The reason is in general, consumers of an API should be discouraged from coupling to heavily to implementation details. For example, private reflection is a classic example. Every change to software has the potential to be a breaking change. People could be relying on timing of your code and a performance optimization could break their apps. But these are cases where perhaps they get what they deserve when a minor change breaks them.

I'll close this since there's nothing actionable here, but feel free to continue the discussion or reopen if the answer is not satisfactory. 😄

[krzysiekpiasecki]

But what about substantial behavioral changes? There are times that you make big changes in a code behavior without changing a thing on its API. Is that a patch?

From point 7:

It MAY be incremented if substantial new functionality or improvements are introduced within the private code.

Release as Minor.

[tallesl]

@haacked

I'm A-OK with most of the remarks you made, specially the last one on relying too much on implementation details.

The behavior of an API is part of the API, not just the shape of the API.

But I'll have to disagree with you here. I think you can use the term "API" loosely implying the code that is underneath it (as a synonym for "program" or "library"), but in a strict sense I wouldn't think so. An API It's an (application programming) interface!

Take Wikipedia's definition for instance:

An API expresses a software component in terms of its operations, inputs, outputs, and underlying types, defining functionalities that are independent of their respective implementations, which allows definitions and implementations to vary without compromising the interface.

There's a note on FAQ addressing this issue:

Use your best judgment. If you have a huge audience that will be drastically impacted by changing the behavior back to what the public API intended, then it may be best to perform a major version release, even though the fix could strictly be considered a patch release. Remember, Semantic Versioning is all about conveying meaning by how the version number changes. If these changes are important to your users, use the version number to inform them.

My point is that this remark is just too important to be left on FAQ. In my opinion, the summary and the introduction gives the impression that to come with a version number is just a matter of taking a look on the API.

[FichteFoll]

An API usually makes promises about what happens when you use it in a certain way (like arguments). If the API states in its documentation "sends an email" then changing the way the email is sent is not a breaking change to the API. If it states "sends a plaintext email" and you start sending multi-part mime, it becomes a breaking and major change.

[haacked]

I should have been more precise. SemVer is typically used to version a package or library. If the behavior changes significantly, then you increment the major version of the library.

Your example with the singleton assumes an implementation as the change is in behavior and not the API. So I assumed your example really referred to a library because as you point out, an API is independent of an implementation so talking about a behavior change doesn't make sense in the context of the API.

In sum, if the API doesn't change, its version doesn't. But a specific implementation of it might version independently of the API it implements.

[tallesl]

If the behavior changes significantly, then you increment the major version of the library.

Agreed.

In sum, if the API doesn't change, its version doesn't.

If there was no change in the API and no change in implementation, well, nothing changed. If there was no change in the API but there was a change in implementation you have to change the version, after all you have something to distribute here.

But a specific implementation of it might version independently of the API it implements.

I sincerely didn't get this one. Are you mentioning things like Java folks that creates packages that are only an API without any implementation at all?

---

I think we're starting to repeat ourselves here. I just want to end here saying that if you combine the definition of API

An API expresses a software component in terms of its operations, inputs, outputs, and underlying types, defining functionalities that are independent of their respective implementations

with what the spec says on its introduction

Bug fixes not affecting the API increment the patch version, backwards compatible API additions/changes increment the minor version, and backwards incompatible API changes increment the major version.

it gives the wrong impression what breakage really is (behavior is completely left out).

[crazedsanity]

Well, look at it this way: how much does the implementor have to change when upgrading?

Consider it in simpler terms, from the perspective of the implementor (the developer that's actually utilizing the library in question):

PATCH: I can upgrade with no change to the code.
MINOR: There's some work to do, but nothing substantial
MAJOR: Plenty of code to change/refactor/rewrite

[tallesl]

@crazedsanity

By not using the word "API" you didn't step in the confusion I'm addressing in this issue. The spec on the other hand does use the word.

[haacked]

@tallesl I see your point. In the introduction to SemVer, it starts off by talking about packages.

The bigger your system grows and the more packages you integrate into your software, the more likely you are to find yourself, one day, in this pit of despair.

And then it moves into a discussion of the API without really defining API.

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

So if we strictly define API as just the "interface" a breaking change that doesn't change the interface wouldn't change the major version.

I never noticed this because I always read this as:

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

So the question is, what's the best most minimal way to address this?

[tallesl]

@haacked

I think the best/most minimal way to address this is by adding a short statement on the introduction stating what we have been discussing here. I also would recommend to add it just after the quote that uses "API" to define what patch, minor and major is (that's the troublesome part IMO).

What about

This may consist of documentation or be enforced by the code itself. Regardless, it is important that this API be clear and precise. Once you identify your public API, you communicate changes to it with specific increments to your version number. Consider a version format of X.Y.Z (Major.Minor.Patch). Bug fixes not affecting the API increment the patch version, backwards compatible API additions/changes increment the minor version, and backwards incompatible API changes increment the major version. Also, use your best judgment, if you have an audience that may be impacted by a change in behavior of the API consider performing a major version release, even though could strictly be considered a patch release.

It's a slightly modified sentence from the FAQ.

[haacked]

I like it, but want to tweak it a bit. How about?

Keep in mind that the purpose of Semantic Versioning is to communicate the risk that a change will impact your audience. It's possible that a change to a package does not change the public API, but does change the behavior enough to break most consumers. In such a scenario, consider incrementing the major version even though it could strictly be considered a patch release if you looked only at the change to the API surface.

[tallesl]

Even better 👍

P.S.: Maybe that FAQ statement becomes redundant now that we "promoted" the remark to the introduction, even though they are not literally identical.

[krzysiekpiasecki]

But what about substantial behavioral changes?
Suppose there's a library that sends emails. Let's say that on version 1.0.0 it simply sends emails as plain text, no configuration there.
On its second release the author changes the library to send emails as HTML instead, without changing anything on its API. It does that automatically. What's the version?

IMHO you have probably developed a new library function, so next release is 1.1.0 but you MUST still support the old function, which sends plain text until next MAJOR because of old clients. You can manifest also old function as deprecated if you want remove this function in a future with next MAJOR release.

[israel-lugo]

I would suggest that (the main?) part of the problem is with the term "API". It seems some people read it as "the sum of your program's public functions and their expected behavior", with "behavior" being left for a case-by-case analysis, whereas some people read "API" in the stricter sense of "Application Programmer Interface".

I've opened issue #331 for discussing precisely this matter. I believe "API" is too limiting and could be improved by replacing it e.g. with "Interface" or something that means "the full interaction with the program".

Yes, an introduction can be added, and a FAQ entry and so on, but perhaps if we find a better suited term, the extra explanations cease to be necessary.