Skip to content

Commit a73817d

Browse files
committed
Add info about Cargo.lock.msrv to Contributing.md
This is so that contributors (external or internal) are able to find information about how to deal with failures in min_rust CI job.
1 parent e86823b commit a73817d

File tree

1 file changed

+32
-0
lines changed

1 file changed

+32
-0
lines changed

CONTRIBUTING.md

+32
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,38 @@ Starting a cluster without running any test is possible with `make up`.
5454
Before sending a pull request, it is a good idea to run `make ci` locally (or `make dockerized-ci` if on macOS).
5555
It will perform a format check, `cargo check`, linter check (clippy), build and `cargo test`.
5656

57+
### min_rust workflow and Cargo.lock.msrv
58+
59+
There is min_rust job defined in rust.yml workflow that checks if the driver compiles with our current MSRV.
60+
Bumping MSRV is generally not considered a breaking change, so our dependencies are free to do it,
61+
and do it regularly. This resulted in failures in this job.
62+
We could pin versions of problematic crates in Cargo.toml, but it would affect version selection
63+
for client applications. It would also force people that use non-ancient versions of Rust to use older
64+
versions of dependencies, which is not desirable.
65+
66+
We opted for a different approach. There is Cargo.lock.msrv file in repository, which is used only by min_rust job -
67+
it is renamed to Cargo.lock before building the driver with `--locked` flag.
68+
69+
This solution is good for us (because we don't have to fix breakage so often) and for users of the driver on modern versions
70+
of Rust - for them the driver will just work.
71+
Users on old versions of Rust will potentially have to pin indirect dependencies to specific versions - but that shouldn't be
72+
that much of a problem, it's just few `cargo update` commands.
73+
74+
If your PR added / removed / updated a dependency, you will need to also update Cargo.lock.msrv file.
75+
There are a few scenarios:
76+
- If you just bumped version of one of crates in the workspace: rename Cargo.lock.msrv to Cargo.lock,
77+
run `cargo check --all-targets --all-features --offline`, rename the file back.
78+
- If you added / removed / updated dependency in one of `Cargo.toml` files it should be enoug to
79+
rename rename Cargo.lock.msrv to Cargo.lock, run `cargo check --all-targets --all-features`
80+
and rename the file back.
81+
- If previous methods didn't work or you want to recreate the file (which we should do once in a while):
82+
1. Switch to MSRV version (e.g. `rustup install 1.66 && rustup default 1.66`). Check README.md file for current MSRV.
83+
2. Remove your Cargo.lock
84+
3. Run `cargo check --all-targets --all-features`
85+
4. If you got an error about one of dependencies not working with this version of Rust, update it's version in `Cargo.lock`,
86+
using command like `cargo update -p toml_datetime --precise 0.6.3` and go back to step 3.
87+
5. Rename `Cargo.lock` to `Cargo.lock.msrv`.
88+
5789
## Contributing to the book
5890
5991
The documentation book is written using [mdbook](https://github.com/rust-lang/mdBook)\

0 commit comments

Comments
 (0)