From f724954246434a3346f8d69f631c297cdc0837a1 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Fri, 6 Dec 2024 17:02:33 -0500 Subject: [PATCH] Add deprecation / API removal policy --- README.md | 18 ++++++++++++++++++ arrow/README.md | 2 +- parquet/README.md | 2 +- 3 files changed, 20 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 57794b1d6a4..c13e92b3a70 100644 --- a/README.md +++ b/README.md @@ -82,6 +82,24 @@ versions approximately every 2 months. [`object_store`]: https://crates.io/crates/object_store +### Deprecation Policy + +Minor releases may deprecate, but not remove APIs. Deprecating APIs allows the +Rust programs to still compile, but will generate compiler warnings. This gives +downstream crates time to migrate to non deprecated APIs prior to their removal. + +All deprecated APIs are marked using the `#[deprecated]` attribute with both the +first version they were deprecated in, as well as what new API to use instead. + +```rust +#[deprecated(since = "51.0.0", note = "Use `date_part` instead")] +``` + +Deprecated APIs will be kept for at least one major release after they were +deprecated. For example, an API deprecated in `51.3.0` will not be removed until +at least `53.0.0`. Given the planned release schedule, this is typically between +3 and 6 months. + ## Related Projects There are several related crates in different repositories diff --git a/arrow/README.md b/arrow/README.md index a1444005ec0..79aefaae905 100644 --- a/arrow/README.md +++ b/arrow/README.md @@ -37,7 +37,7 @@ This crate is tested with the latest stable version of Rust. We do not currently The `arrow` crate follows the [SemVer standard] defined by Cargo and works well within the Rust crate ecosystem. See the [repository README] for more details on -the release schedule and version. +the release schedule, version and deprecation policy. [SemVer standard]: https://doc.rust-lang.org/cargo/reference/semver.html [repository README]: https://github.com/apache/arrow-rs diff --git a/parquet/README.md b/parquet/README.md index e9f52ff279d..9ff1d921d69 100644 --- a/parquet/README.md +++ b/parquet/README.md @@ -36,7 +36,7 @@ This crate is tested with the latest stable version of Rust. We do not currently The `parquet` crate follows the [SemVer standard] defined by Cargo and works well within the Rust crate ecosystem. See the [repository README] for more details on -the release schedule and version. +the release schedule, version and deprecation policy. [semver standard]: https://doc.rust-lang.org/cargo/reference/semver.html [repository readme]: https://github.com/apache/arrow-rs