If encodeText is part of the API of the program then it's a breaking change. Because now you replace "foo" with something else.
Regarding bug fixes, it depends on the scope I guess. If the bug fix changes the behavior so much that with the old version the program users were relying on something that was faulty and now it's doing the right thing but that thing has a different outcome, it's a breaking change.
What makes it hard is that fixing any bug would change the behaviour as the code goes from bug to bug free. If it had no behavioural change, the bug couldn't be fixed.
It is totally a trade off though as it would get ridiculous jumping major versions for every bug fix. I guess the intention of SemVer isn't to be that pedantic though.
I have written code before where I captured exceptions to look at the specific exception message to perform an action. I'm sure the developers would have never considered the exception message a breaking change. I consider this now bad code but it does show how we can depend on the unintentional.
It's pronounced Diane. I do data architecture, operations, and backend development. In my spare time I maintain Massive.js, a data mapper for Node.js and PostgreSQL.
The difference is that the behavior of a bug is unanticipated. If I call your encodeText function, it's because I want to transform 'abbreviate' into 'xyzbbrevixyzte'. If it throws when I pass in 'abbŗévīaţè' and you fix it to handle expanded character sets, you're not interfering with existing usages so there's no reason for it to be more than a semver-patch bump. If, however, the fix means that the function no longer works for length-1 strings for arcane Unicode reasons, it's still a bugfix but one with a breaking change involved which requires a semver-major bump.
If encodeText suddenly turns 'abbreviate' into 'xyzfoofoorevixyzte' instead, that's either a breaking change (semver-major) or a bug which should be fixed with a semver-patch bump.
Recently we had an app break because of the following reasons:
version 4.4.0 was released with the following changelog message: Backport security fix from 5.x for token revocation when using public clients
we applied the security fix knowing revocation wasn't an issue for our use case
the security fix went to production without deep testing
Android users started complaining, iOS users were fine
after reverting and debugging we noticed a difference between the two: Android clients didn't send the client secret, iOS did
the security fix set confidential to true which seems to disable clients without client secret
Setting it to false fixed the issue.
My question is: shouldn't a breaking change like this be clearer?
The changelog doesn't mention it, the upgrade guide says to add the migration but it doesn't clearly state: "hey, the default will break clients without client secret key"
Expected behavior
Either the default should change or the documentation should be clearer about this change.
If
encodeText
is part of the API of the program then it's a breaking change. Because now you replace "foo" with something else.Regarding bug fixes, it depends on the scope I guess. If the bug fix changes the behavior so much that with the old version the program users were relying on something that was faulty and now it's doing the right thing but that thing has a different outcome, it's a breaking change.
What makes it hard is that fixing any bug would change the behaviour as the code goes from bug to bug free. If it had no behavioural change, the bug couldn't be fixed.
It is totally a trade off though as it would get ridiculous jumping major versions for every bug fix. I guess the intention of SemVer isn't to be that pedantic though.
I have written code before where I captured exceptions to look at the specific exception message to perform an action. I'm sure the developers would have never considered the exception message a breaking change. I consider this now bad code but it does show how we can depend on the unintentional.
The difference is that the behavior of a bug is unanticipated. If I call your
encodeText
function, it's because I want to transform 'abbreviate' into 'xyzbbrevixyzte'. If it throws when I pass in 'abbŗévīaţè' and you fix it to handle expanded character sets, you're not interfering with existing usages so there's no reason for it to be more than a semver-patch bump. If, however, the fix means that the function no longer works for length-1 strings for arcane Unicode reasons, it's still a bugfix but one with a breaking change involved which requires a semver-major bump.If
encodeText
suddenly turns 'abbreviate' into 'xyzfoofoorevixyzte' instead, that's either a breaking change (semver-major) or a bug which should be fixed with a semver-patch bump.I just read this old issue report that might be relevant. Sometimes backports introduce breaking changes that aren't foreseen :D
Consider defaulting Application.confidential to false #1142
Recently we had an app break because of the following reasons:
Backport security fix from 5.x for token revocation when using public clients
Setting it to false fixed the issue.
My question is: shouldn't a breaking change like this be clearer?
The changelog doesn't mention it, the upgrade guide says to add the migration but it doesn't clearly state: "hey, the default will break clients without client secret key"
Expected behavior
Either the default should change or the documentation should be clearer about this change.
Thank you
Wow, that is a subtle breaking change!