zarrs_object_store: Add docs about precise version selection

LDeakin · Nov 15, 2024 · fe3dcec · fe3dcec
1 parent a205956
commit fe3dcec
Show file tree

Hide file tree

Showing 3 changed files with 23 additions and 0 deletions.
diff --git a/zarrs_object_store/CHANGELOG.md b/zarrs_object_store/CHANGELOG.md
@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+ - Add docs about precise version selection
+
 ### Changed
  - Bump `zarrs_storage` to 0.3.0-dev
  - **Breaking**: Bump MSRV to 1.77 (21 March, 2024)

diff --git a/zarrs_object_store/README.md b/zarrs_object_store/README.md
@@ -24,6 +24,16 @@ let store: AsyncReadableWritableListableStorage =
 ## Version Compatibility Matrix
 See [doc/version_compatibility_matrix.md](./doc/version_compatibility_matrix.md).
 
+`object_store` is re-exported as a dependency of this crate, so it does not need to be specified as a direct dependency.
+
+However, if `object_store` is a direct dependency, it is necessary to ensure that the version used by this crate is compatible.
+This crate can depend on a range of semver-incompatible versions of `object_store`, and Cargo will not automatically choose a single version of `object_store` that satisfies all dependencies.
+Use a precise cargo update to ensure compatibility.
+For example, if this crate resolves to `object_store` 0.11.1 and your code uses 0.10.2:
+```shell
+cargo update --package object_store:0.11.1 --precise 0.10.2
+```
+
 ## Licence
 `zarrs_object_store` is licensed under either of
  - the Apache License, Version 2.0 [LICENSE-APACHE](./LICENCE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0> or

diff --git a/zarrs_object_store/src/lib.rs b/zarrs_object_store/src/lib.rs
@@ -19,6 +19,16 @@
 //!
 #![doc = include_str!("../doc/version_compatibility_matrix.md")]
 //!
+//! `object_store` is re-exported as a dependency of this crate, so it does not need to be specified as a direct dependency.
+//!
+//! However, if `object_store` is a direct dependency, it is necessary to ensure that the version used by this crate is compatible.
+//! This crate can depend on a range of semver-incompatible versions of `object_store`, and Cargo will not automatically choose a single version of `object_store` that satisfies all dependencies.
+//! Use a precise cargo update to ensure compatibility.
+//! For example, if this crate resolves to `object_store` 0.11.1 and your code uses 0.10.2:
+//! ```shell
+//! cargo update --package object_store:0.11.1 --precise 0.10.2
+//! ```
+//!
 //! ## Licence
 //! `zarrs_object_store` is licensed under either of
 //! - the Apache License, Version 2.0 [LICENSE-APACHE](https://docs.rs/crate/zarrs_object_store/latest/source/LICENCE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0> or