Semantic Versioning?

[eitsupi]

Ref: pola-rs/polars#24208

It seems like minor version upgrades of planus don't meet the version compatibility expected by cargo and could break downstream package behavior?

[TethysSvensson]

Thank you for pointing this out, we're definitely lacking documentation about which parts of our library are covered by our versioning guarantees and which parts are not.

Our public API and the API of the code generated are covered by semantic versioning. However the internal APIs used by the generated code are not covered.

In practice this means that any crate that contain code generated by the planus CLI must pin the version of the planus library to be the exact same version used to generate the code.

All other libraries, including the ones depending on the generated code can use semantic versioning as normal though.

We are currently enforcing this by doing a check for an exact version match at the top of the generated code. We've done it this way, because getting weird compilation errors in generated code terrible user experience.

I would be open to relaxing this check slightly in the future. In the meantime we should definitely add some documentation in the README.

[eitsupi]

Thanks for the quick reply!
Documentation updates should be helpful.