Versioning and Updates
This part of the tutorial documents how the qFALL crates evolve between minor releases. For every release that requires action on your side, it lists what is new, which bugs were fixed, and how to move your code to the new version.
Semantic Versioning
All qFALL crates follow Semantic Versioning.
As long as the crates are not stable yet, i.e. before version 1.0.0, the following rules apply:
- Minor version updates, e.g.
0.1.x→0.2.0, may introduce API-breaking changes. - Patch version updates, e.g.
0.2.0→0.2.1, are backwards compatible and only contain bug fixes, documentation, or non-breaking additions.
Hence, we recommend to fix the minor version in your Cargo.toml, which is also what cargo add does by default.
[dependencies]
qfall-math = "0.2"
qfall-tools = "0.2"
qfall-schemes = "0.2"
With this requirement, cargo update pulls in patch releases automatically, but never moves you to the next minor version without you editing your Cargo.toml.
Released Versions
| Version | qfall-math | qfall-tools | qfall-schemes |
|---|---|---|---|
0.1.0 | ❌ | ❌ | ❌ |
0.1.1 | ❌ | – | ❌ |
0.2.0 | ✅ | ✅ | ✅ |
0.2.1 | ✅ | – | – |
✅ available on crates.io, ❌ yanked, – not released
We aimed for maximal compatibility and allowed any 0.x version of several dependencies.
Breaking changes in these dependencies, e.g. rand 0.10 and sha2 0.11, broke the 0.1 releases. Hence, we yanked them.
Using 0.1 Releases Today
The following combinations still build, if the listed dependencies are fixed in your Cargo.lock.
qfall-math | qfall-tools | qfall-schemes | Dependencies to fix |
|---|---|---|---|
0.1.1 | 0.1.0 | 0.1.1 | none |
0.1.1 | 0.1.0 | 0.1.0 | sha2 0.10 |
0.1.0 | 0.1.0 | 0.1.0 | sha2 0.10, rand 0.9, rand_distr 0.5 |
Compatible Versions Across Crates
The three crates build on each other: qfall-tools depends on qfall-math, and qfall-schemes depends on both.
Always update them together and use the same minor version for all qFALL crates in your project.
qfall-schemes | qfall-tools | qfall-math | FLINT binding | Minimum Rust version |
|---|---|---|---|---|
0.1 | 0.1 | 0.1 | flint-sys 0.7 (FLINT 2.8) | 1.85 |
0.2 | 0.2 | 0.2 | flint3-sys 3.6 (FLINT 3.6) | 1.88 |
The 0.1 and 0.2 releases cannot be mixed in one project.
Both FLINT bindings, flint-sys and flint3-sys, link the native library flint, and Cargo allows only one crate per native library in a dependency tree.
Hence, if any dependency of your project still requires a 0.1 release, Cargo fails to resolve the dependencies with an error mentioning links = "flint".
In this case, update that dependency as well.
How to Update
- Read the update notes of the target version, in particular its How to Transition chapter.
- Ensure your Rust toolchain is recent enough, e.g. via
rustup updateandrustc --version. - Update all qFALL crates at once, e.g. via
cargo add qfall-math@0.2 qfall-tools@0.2 qfall-schemes@0.2 - Run
cargo clean,cargo buildand work through the compiler errors with the help of the transition guide. - Run your tests. Some changes, which are listed in the chapter on bug fixes, change the output of functions without changing their signature.
If you encounter problems that are not covered here, please open an issue in the GitHub repository of the respective crate.