Suggestion: Please Maintain Backward Compatibility for Minor Version Updates

[bean-du]

Hi there,

Thank you for your work on the rig crate — it’s a promising and useful project that we’ve been integrating into our Rust applications.

However, I’ve noticed a serious usability issue: minor version updates of rig often introduce breaking changes, such as modifications to function signatures, parameter formats, or output structures. This creates a high maintenance burden and makes upgrading between versions unnecessarily costly and risky.

⸻

Suggestions for Improvement 1. Follow Semantic Versioning According to semver, minor version updates (x.y.z → x.y+1.z) should not break existing public APIs. Breaking changes should only be introduced with a major version bump. 2. Stabilize the Public API Before Further Refactoring • Consider locking down the key APIs — function names, argument and return types, error handling — before making further internal or architectural changes. • You can use traits or wrapper modules to isolate internal evolution from external contracts. 3. Provide Clear and Transparent CHANGELOGs Please keep a consistent and detailed CHANGELOG.md to document any API-level or behavior changes in each release, so users can upgrade with confidence and awareness. 4. Deprecate Instead of Removing Immediately When changing or removing existing functions, consider marking them as #[deprecated] first and providing a migration path. This avoids hard breaks and gives users time to adapt. 5. Offer a Stable Branch or LTS Version If the crate is evolving quickly, a stable or long-term support (LTS) version would help teams who need predictable upgrades in production environments.

⸻

🙏 Final Thoughts

Rust is a language that empowers developers to build reliable systems with confidence. The ecosystem benefits greatly when crates like rig embrace API stability and semver best practices. Frequent breaking changes in minor versions make it difficult to adopt and rely on this otherwise valuable crate.

I hope you’ll consider these suggestions — and if needed, I’d be happy to help contribute ideas, designs, or tests to improve the developer experience.

Thanks again for your work!

[linear[bot]]

RIG-835 Suggestion: Please Maintain Backward Compatibility for Minor Version Updates

[joshua-mo-143]

Hi @bean-du, thanks for opening this issue!

Yes - currently we're pre-1.0 so there may or may not be breaking changes between versions and this is stated on the repo README. However, we've started to pick up a fair amount of traction recently in projects going to production and I don't think that the recent flight path of pretty much just making constant breaking changes is the way forward long-term (although they've been necessary so that we can improve the framework, as many of the original design choices were not really the most flexible in some respects).

This being said, I believe most of the breaking changes going forward will have a clear migration path and a lot of the changes after next release will be primarily be concerned with ensuring that we don't have to make breaking changes as often. For any changes where the solution isn't immediately obvious, a migration path will be provided by us.

This work also covers #609 #604 #598 and #494 (... once we're able to figure out the scope for it).

[Sytten]

Pre-v1 crates in Rust are expected to break between minor updates, though having a good CHANGELOG is nice to have.