A hypothetical question: fix to impossible/infeasible APIs?

[ahyangyi]

Consider the following two situations:

A project libfoo releases v1.0.0. It contains two headers: foo.h and foo_utils.h. Due to some mistakes, any code that includes foo_utils.h will fail to compile, since the API declarations are broken. However, since libfoo is pretty useful, people already start using foo.h and avoid foo_utils.h.

In this case, releasing a simple fix to the API declarations in foo_utils.h as v1.0.1 or v1.1.0 makes sense to me, since it will surely break no one's workflow, and the fix might not be deemed significant enough (since people who are already using libfoo can migrate to the new version without any hassle and there is little to no change to the underlying algorithms).

What's the recommended versioning practice in this case?

A project libbar includes a function called "check_halt", which checks if a callback can eventually halt. After learning something about the Halting Problem, the author realizes that this API does not make sense, since it cannot be realistically implemented at all. And anyone trying to build upon this API is surely doomed by a mathematical proof.

In this case, the API is broken beyond repair, and it's broken due to its very existence. Is it OK to remove it without incrementing the major version?

[ghost]

I think I would try to follow Semantic Versioning guidelines (http://semver.org) to address these issues. I'll only respond to #1 here. If the API declaration is updated in an attempt to fix incorrect behavior, but there are no new functionalities or other improvements to the code base, then this sounds like a backwards compatible bug fix. Compare #6 and #7 in the referenced webpage. As such, it would fall under a PATCH version change, i.e. v.1.0.0 -> v.1.0.1. At least this is how I interpret your description of the issue.

[PanisSupraOmnia]

Unless I'm misunderstanding, I think that the 2nd situation could possibly be a PATCH version change as well, seeing as the "functionality" is fixed by removing it - and I this might count as backwards compatible, because it obviously wouldn't have really worked before. However, now that I think about it some more, an argument could definitely be made that the best case would be immediate deprecation (requiring MINOR increment) and removal ASAP (requiring MAJOR increment). I have to say I'm leaning towards the latter, just because there is the possibility of it actually being used.

[enkessler]

Case 1: PATCH increase.

The declared and intended API/behavior did not change. Had it worked before, it would still be working now. The fact that it didn't work is why it's called a bug and you are fixing it. If users have been relying on the bugged behavior, well, then they weren't following the declared and intended API and problems (such as their code being broken by the bug fix) are to be expected when one doesn't follow instructions.

Case 2: MINOR increase + MAJOR increase.

The declared and intended API/behavior is going to change. Sure, it was not a smart idea to try and provide impossible functionality in the first place but it was promised, all the same. Deprecate it with a MINOR version increase and get rid of it with a MAJOR version increase.

[jwdonahue]

@ahyangyi, unless you need further assistance with this, please close this issue.