Repository navigation
docs: explicitly note what is/is not covered under SemVer / breaking change guarantees #2168
Description
Related to #2163, but this has been on my (internal, mental) backlog for some time
Related to #2163, but this has been on my (internal, mental) backlog for some time
Activity
mromaszewicz commentedon Aug 1, 2026
Yeah, this is a hard one.
We do our best not to make breaking changes. If they are changes to common patterns, we tend to flagify them. If we are off in the weeds of uncommon specs, or weird edge cases, I tend not to complicate the code with special casing to preserve old behavior, but it's always a judgment call, and we sometimes get it wrong.
Most of the problems around name normalization, naming of types and even mapping of oapi types to go types can be solved by allowing full customization, rather than hardcoded behavior. Right now, we support customizing the type mapping, the way struct tags are emitted, and we now need to have a way to customize name normalization. Currently, it's a Go function, and we could allow users to build their own oapi-codegen commandline which registers a different function, but this is heavy weight. If we allow users to control these transformations, most of the problems for which we release breaking changes would disappear.