I currently manage a library which has a lot of public usage, and I had a question about semantic versioning. I want to refactor one fairly important part of the library which is implemented incorrectly – and has always been implemented incorrectly. But doing this would mean changes to the public API, which is a major decision.
The change I want to make revolves around how iterators are used. Currently, users have to do this:
while ($element = $iterator->next()) {
// ...
}
Which is incorrect, at least in PHP's native Iterator interface. I want to replace with this:
while ($iterator->valid()) {
$element = $iterator->current();
// ...
$iterator->next();
}
which is analogous to:
foreach ($iterator as $element) {
// ...
}
If you look at Tom's guide to semantic versioning, he clearly states that any changes to the public API (i.e. those which are not backward compatible), should justify a major release. So the library would jump from 1.7.3 to 2.0.0 which, for me, is a step too far. We're only talking about one feature being fixed.
I do have plans to eventually release 2.0.0, but I thought this was when you completely rewrote the library and implemented numerous public API changes. Does the introduction of this refactoring warrant a major version release? I really can't see how it does – I feel more comfortable releasing it as 1.8.0 or 1.7.4. Does anybody have some advice?
Best Answer
You hesitate because you don't want to make semantic versioning, you want to make "advertisement supporting versioning". You expect a version number "2.0" to tell the world that you have a bunch of new cool features in your library now, not that you changed the API. That's ok (many software companies and/or developers do that). IMHO you have the following options:
next, just add thevalidandcurrentfunctions). Then you can use "1.8.0" as the next version number. If you think changing the behaviour ofnextis really important, do it in 2.0.0.