I'm the maintainer of a library called python-json-logger, which follows Semantic Versioning. I'm grappling with whether a recent change should be classified as a major, minor, or patch release. The change I'm considering modifies how special prefixes work when loading classes from a dictConfig or fileConfig so that they align with standard library behavior. This adjustment allows Python objects to be loaded by name (for instance, the string 'stream: ext://sys.stderr' will now pass 'sys.stderr' instead).
Since this behavior wasn't officially supported in the past, I wonder if this constitutes a bug fix or merely an API compatible change. On the one hand, their signatures remain unchanged, which could suggest a patch or minor release. On the other, the library never intended to handle these special prefixes, which might make this a breaking change, warranting a major version increment. I'd appreciate any insights before rolling this out and potentially disrupting users' builds!
5 Answers
It's great to see you really considering the impact of this change. More people should take a step back and question their evaluations in these situations!
What if you introduced an option to enable this new behavior while keeping it off by default? That way, you could add the feature without disrupting existing users. Additionally, was 'stream: ext://sys.stderr' a valid identifier before this change? If so, it sounds like a breaking change to me. If it wasn't intended to be supported, then it feels more like a new feature than a bug fix. Just something to consider!
I would personally go for a minor version bump. While you can argue it’s a bug fix, there’s enough new behavior introduced to warrant a more significant version change. Nonetheless, the behavioral shifts don't seem severe enough to require a major version change since it shouldn’t break reasonable configurations.
I'd play it safe and opt for the major version increase. It’s important to make clear to your users that significant changes have occurred and guide them on how to adjust their configurations accordingly.
You're definitely changing the API here; the same input will yield a different output (string vs. stream). This really points towards needing a major version bump. If these changes were to private attributes, you'd be safe, but since they're public functions, it merits a major version increase. However, if you make this new behavior toggled off by default, it'll remain backward-compatible.
Absolutely agree! Altering the behavior of a public interface definitely necessitates a major version bump. Just ensure there's clear notification for users about the breaking change.
I see what you're saying, but an API is based on what you document. If this isn't clearly defined in your documentation, any changes might be viewed more leniently as new features instead of prohibited alterations.