This is an automated email from the ASF dual-hosted git repository.
alamb pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-rs-object-store.git
The following commit(s) were added to refs/heads/main by this push:
new c96bcb1 Update README.md and Contributing guidelines (#8)
c96bcb1 is described below
commit c96bcb180a245d877bdf21f6fffa3125dc04ce58
Author: Andrew Lamb <[email protected]>
AuthorDate: Mon Mar 24 14:00:52 2025 -0400
Update README.md and Contributing guidelines (#8)
* Add release schedule, deprecation guides
* Add related repositories
* Apply suggestions from code review
Co-authored-by: Raphael Taylor-Davies
<[email protected]>
---------
Co-authored-by: Raphael Taylor-Davies
<[email protected]>
---
CONTRIBUTING.md | 28 ++++++++++++++++++++++++++++
README.md | 30 +++++++++++++++++++++++++++++-
2 files changed, 57 insertions(+), 1 deletion(-)
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 |
