From 55300a6b728de90908858918abb65f941f93ccd9 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Thu, 20 Mar 2025 16:21:32 -0400 Subject: [PATCH 1/3] Add release schedule, deprecation guides --- CONTRIBUTING.md | 28 ++++++++++++++++++++++++++++ README.md | 20 +++++++++++++++++++- 2 files changed, 47 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5444ec74..37095ebd 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 arrow-rs 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. + +Foe 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 1799bf8b..58532494 100644 --- a/README.md +++ b/README.md @@ -38,10 +38,28 @@ 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 +``` + +## 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 | From 03ffd105c7d50ad65dde00ecf07e236baaad8651 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Thu, 20 Mar 2025 16:24:57 -0400 Subject: [PATCH 2/3] Add related repositories --- README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/README.md b/README.md index 58532494..53af7423 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,16 @@ It's possible to build `object_store` for the `wasm32-unknown-unknown` target, h cargo build -p object_store --target wasm32-unknown-unknown ``` +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 From 9c387d4ace8be612e398b191ed25e5acf940779a Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Fri, 21 Mar 2025 12:27:31 -0400 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Raphael Taylor-Davies <1781103+tustvold@users.noreply.github.com> --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 37095ebd..ecf2d3a0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -210,14 +210,14 @@ 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 arrow-rs version in which it was deprecated +- 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. -Foe example +For example ```rust #[deprecated(since = "0.11.0", note = "Use `date_part` instead")]