From f724954246434a3346f8d69f631c297cdc0837a1 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Fri, 6 Dec 2024 17:02:33 -0500 Subject: [PATCH 1/5] 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 57794b1d6a46..c13e92b3a70a 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 a1444005ec00..79aefaae9053 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 e9f52ff279d5..9ff1d921d692 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 From da4527b8a9b7d6cbed85f187463ab9a543cf0bd4 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Sat, 7 Dec 2024 07:45:27 -0500 Subject: [PATCH 2/5] Increase proposal to 2 releases --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index c13e92b3a70a..ca2ff38e1495 100644 --- a/README.md +++ b/README.md @@ -89,16 +89,16 @@ 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. +first version they were deprecated in, and 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 APIs will be kept for at least two major releases 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. +at least `54.0.0`. Given the planned release schedule, this is typically between +6 and 9 months. ## Related Projects From 01c6977f50583394838e73b163fe6cfc7031a22e Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Thu, 12 Dec 2024 07:33:43 -0500 Subject: [PATCH 3/5] change from policy to guidelines, add flexibility --- README.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index ca2ff38e1495..a9b37119d273 100644 --- a/README.md +++ b/README.md @@ -82,11 +82,11 @@ versions approximately every 2 months. [`object_store`]: https://crates.io/crates/object_store -### Deprecation Policy +### Deprecation Guidelines -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. +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. All deprecated APIs are marked using the `#[deprecated]` attribute with both the first version they were deprecated in, and what new API to use instead. @@ -95,10 +95,12 @@ first version they were deprecated in, and what new API to use instead. #[deprecated(since = "51.0.0", note = "Use `date_part` instead")] ``` -Deprecated APIs will be kept for at least two major releases after they were -deprecated. For example, an API deprecated in `51.3.0` will not be removed until -at least `54.0.0`. Given the planned release schedule, this is typically between -6 and 9 months. +In general, deprecated APIs will be kept for at least two major releases after +they were deprecated (typically between 6 - 9 months later). For example, an API +deprecated in `51.3.0` can be removed in `54.0.0` (or later). Deprecated APIs +may be removed earlier or later than these guidelines at the discretion of the +maintainers. + ## Related Projects From 1f5bf654e2c7dc2d717ebc66fca942cb97662e90 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Thu, 12 Dec 2024 07:36:20 -0500 Subject: [PATCH 4/5] prettier --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index a9b37119d273..c021dc3cb230 100644 --- a/README.md +++ b/README.md @@ -101,7 +101,6 @@ deprecated in `51.3.0` can be removed in `54.0.0` (or later). Deprecated APIs may be removed earlier or later than these guidelines at the discretion of the maintainers. - ## Related Projects There are several related crates in different repositories From 9fcc60c3652397e404a934367ea41269fda9871d Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Tue, 17 Dec 2024 14:28:35 -0500 Subject: [PATCH 5/5] Make instructions more actionable --- README.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index c021dc3cb230..4d1b43926952 100644 --- a/README.md +++ b/README.md @@ -88,14 +88,22 @@ 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. -All deprecated APIs are marked using the `#[deprecated]` attribute with both the -first version they were deprecated in, and what new API to use instead. +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 = "51.0.0", note = "Use `date_part` instead")] ``` -In general, deprecated APIs will be kept for at least two major releases after +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 `51.3.0` can be removed in `54.0.0` (or later). Deprecated APIs may be removed earlier or later than these guidelines at the discretion of the