3 ms·
When you think in terms of semver as a social contract, one can also take into consideration what the documentation says. If the docs don't explicitly say you c
by lhorie 6y ago
When you think in terms of semver as a social contract, one can also take into consideration what the documentation says. If the docs don't explicitly say you can do something, then it's entirely reasonable for the library author to say "well, that's relying on undefined behavior, you should not do that".
- simonw 6y agoThis is why when I'm building APIs or libraries that are meant to be used by developers I won't consider a feature "done" until it's both tested AND documented. The documentation is the contract that I use for semver. If something is documented, I can't break it without bumping the major version number. If it's an undocumented internal class or function I can change it any time I like.
- ithkuil 6y agoInteresting things happen around this "undocumented" cases. For example, imagine you expose a "map" API and you explicitly don't mention it's a hash map or some tree. You also don't claim the the iterator will be in order, but you fail to document that you explicitly don't promise any order at all. Some users will not read the documentation and say "wait a minute, it doesn't claim whether any ordering is guaranteed nor it claims the contrary, hence I must assume it's undefined behaviour thus I can't rely on any ordering". Instead some users will look at the behaviour and assume the documentation just forgot to mention that aspect (and if the implementation indeed iterates the map in order they'll just assume that's what the documentation should have written). After all, just as code, documentation can have bugs and will be amended in subsequent releases. Now, you finally realize that you forgot to say "the iteration order is undefined" and make a new release with that documentation fix. The question is: would you consider this a major "breaking" change or a minor point release?
- gen220 6y agoYep! Ironically enough, hyrum's law leaves the ethics of breaking changes ambiguous. Breaking compatibility with customers that are depending on your bugs to remain unfixed is both good (insofar as it removes bad things) and bad (insofar as things that were working work no longer). Another angle on the social contract is visible in that, when we accidentally introduce a major-version change in a patch-version, we don't retroactively change the version number to a major version bump, we just release another patch. :)