Today, I updated ZBateson\MailMimeParser the PHP e-mail parser library from 1.x to 2.x.
Soon enough, my PHP error log started filling up with errors.
Noting where it happened, I found out that it had to do with their ::parse(...) function: https://mail-mime-parser.org/upgrade-2.0
An additional parameter needs to be passed to Message::from() and MailMimeParser::parse() specifying whether the passed resource should be ‘attached’ and closed when the returned IMessage object is destroyed, or kept open and closed manually after the message is parsed and the returned IMessage destroyed.
That is, instead of picking one of those new "modes" by default, the author(s) simply chose to break all existing code.
Frankly, even after re-reading that page multiple times, I have no clue what the new parameter actually does. I have set it to true just to make the errors stop happening, but I'm worried that this is somehow not the right choice.
My point, and question, is: Why do library developers knowingly break existing code like this? Why not at least have it default to either true or false, whichever is the most reasonable?
Before you tell me that I should have read the upgrade instructions before updating, I sometimes do, but when your life consists of nothing but dealing with constant updates of all kinds of software, you eventually get numb to all the changes and stop spending the time and effort to do so. Is it really reasonable that updating a library (in particular) should break existing code?
And this is not some sort of edge-case of the library, either. It's literally the #1 reason for it to exist in the first place, sure to be used by every single user: parsing an e-mail blob!
Best Answer
A major version upgrade literally means they intend to break things. You shouldn't upgrade to a new major version unless you're prepared to deal with it. Most build systems have a way to specify you're okay with automatic upgrades to minor versions, but not to major versions.
APIs break for a number of reasons. In this case, I'm guessing it's because what they would want to set the default to would be surprising to some users, either because it's not a typical convention for the language, or because of history with this library. This way, instead of half the users suddenly getting a difficult to explain "file is closed" error whose reason is difficult to find in the release notes, everyone gets a "missing parameter" error that they can easily look up the purpose of.
Remember, not everyone uses the library the same way as you. When you have a diverse user base, you have to make compromises in the API to accommodate everyone. A change that seems unnecessary to you might be just what another user has been waiting for.