diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5444ec7..ecf2d3a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -200,3 +200,31 @@ OBJECT_STORE_BUCKET=test-bucket \ GOOGLE_SERVICE_ACCOUNT=/tmp/gcs.json \ cargo test -p object_store --features=gcp ``` + + +# Deprecation Guidelines + +Minor releases may deprecate, but not remove APIs. Deprecating APIs allows +downstream Rust programs to still compile, but generate compiler warnings. This +gives downstream crates time to migrate prior to API removal. + +To deprecate an API: + +- Mark the API as deprecated using `#[deprecated]` and specify the exact object_store version in which it was deprecated +- Concisely describe the preferred API to help the user transition + +The deprecated version is the next version which will be released (please +consult the list above). To mark the API as deprecated, use the +`#[deprecated(since = "...", note = "...")]` attribute. + +For example + +```rust +#[deprecated(since = "0.11.0", note = "Use `date_part` instead")] +``` + +In general, deprecated APIs will remain in the codebase for at least two major releases after +they were deprecated (typically between 6 - 9 months later). For example, an API +deprecated in `0.10.0` can be removed in `0.13.0` (or later). Deprecated APIs +may be removed earlier or later than these guidelines at the discretion of the +maintainers. diff --git a/README.md b/README.md index 1799bf8..53af742 100644 --- a/README.md +++ b/README.md @@ -38,10 +38,38 @@ Originally developed by [InfluxData](https://www.influxdata.com/) and later dona See [docs.rs](https://docs.rs/object_store) for usage instructions +See [CONTRIBUTING.md] to learn how to contribute to this project. + +[CONTRIBUTING.md]: https://github.com/apache/arrow-rs-object-store/blob/main/CONTRIBUTING.md + ## Support for `wasm32-unknown-unknown` target It's possible to build `object_store` for the `wasm32-unknown-unknown` target, however the cloud storage features `aws`, `azure`, `gcp`, and `http` are not supported. ``` cargo build -p object_store --target wasm32-unknown-unknown -``` \ No newline at end of file +``` + +Here are several related crates in different repositories + +| Crate | Description | Documentation | +| ------------------------ | ------------------------------------------- | --------------------------------------- | +| [`object_store_opendal`] | Use [`opendal`] as [`object_store`] backend | [(README)][object_store_opendal-readme] | + +[`object_store_opendal`]: https://crates.io/crates/object_store_opendal +[`opendal`]: https://crates.io/crates/opendal +[object_store_opendal-readme]: https://github.com/apache/opendal/blob/main/integrations/object_store/README.md + +## Release Schedule + +The [`object_store`] crate follows [Semantic Versioning]. We aim to release new +versions approximately every 2 months. + +[`object_store`]: https://crates.io/crates/object_store + +Planned Release Schedule + +| Approximate Date | Version | Notes | +| ---------------- | -------- | --------------------------------------- | +| Feb 2025 | `0.12.0` | Major, potentially breaking API changes | +| Apr 2025 | `0.12.1` | Minor, NO breaking API changes |