From b109ba3489d38b3432551d87188165d81b874708 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Mon, 9 Dec 2024 07:30:40 -0500 Subject: [PATCH 1/7] Minor: improve the Deprecation / API health policy --- README.md | 7 ++-- docs/source/library-user-guide/api-health.md | 36 ++++++++++++++++++-- 2 files changed, 38 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 2e4f2c347fe5..38d52d0e1ccb 100644 --- a/README.md +++ b/README.md @@ -140,5 +140,8 @@ DataFusion enforces MSRV policy using a [MSRV CI Check](https://github.com/searc ## DataFusion API evolution policy -Public methods in Apache DataFusion are subject to evolve as part of the API lifecycle. -Deprecated methods will be phased out in accordance with the [policy](https://datafusion.apache.org/library-user-guide/api-health.html), ensuring the API is stable and healthy. +Public methods in Apache DataFusion evolve over time: while we try to maintain a +stable API, we also improve the API over time. As a result, we typically +deprecate methods before removing them, according to the [api health policy]. + +[api health policy]: https://datafusion.apache.org/library-user-guide/api-health.html \ No newline at end of file diff --git a/docs/source/library-user-guide/api-health.md b/docs/source/library-user-guide/api-health.md index 943a370e8172..7e13a6d49d4e 100644 --- a/docs/source/library-user-guide/api-health.md +++ b/docs/source/library-user-guide/api-health.md @@ -19,11 +19,41 @@ # API health policy -To maintain API health, developers must track and properly deprecate outdated methods. +DataFusion is used extensively as a library and has a large public API, thus it +is important that the API is well maintained. In general, we try to minimize +breaking API changes, but they are sometimes necessary. + +When possible, rather than making breaking API changes, we prefer to deprecate +APIs to give users time to adjust to the changes. + +## Breaking Changes + +In general, a function is part of the public API if it appears on the [docs.rs page] + +Breaking public API changes are those that *require* users to change their code +for it to compile, and are listed as "Major Changes" in the [SemVer +Compatibility Section of the cargo book]. Common examples of breaking changes: + +- Adding new required parameters to a function (`foo(a: i32, b: i32)` -> `foo(a: i32, b: i32, c: i32)`) +- Removing a `pub` function +- Changing the return type of a function + +When making breaking public API changes, please add the `api-change` label to +the PR so we can highlight the changes in the release notes. + +[docs.rs page]: https://docs.rs/datafusion/latest/datafusion/index.html +[SemVer Compatibility Section of the cargo book]: https://doc.rust-lang.org/cargo/reference/semver.html#change-categories + +## Deprecation Policy + When deprecating a method: -- clearly mark the API as deprecated and specify the exact DataFusion version in which it was deprecated. -- concisely describe the preferred API, if relevant +- Mark the API as deprecated using `#[deprecated`] and specify the exact DataFusion 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 after the +deprecation PR is merged. For example, if the next scheduled release `41.0.0`, +and a method is deprecated in a PR, the deprecated version will be `41.0.0`. API deprecation example: From c9ba507b7b2cfe31bf30ba550677f80cdda8185a Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Mon, 9 Dec 2024 07:31:08 -0500 Subject: [PATCH 2/7] prettier --- README.md | 2 +- docs/source/library-user-guide/api-health.md | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 38d52d0e1ccb..6ec6e92ea8c1 100644 --- a/README.md +++ b/README.md @@ -144,4 +144,4 @@ Public methods in Apache DataFusion evolve over time: while we try to maintain a stable API, we also improve the API over time. As a result, we typically deprecate methods before removing them, according to the [api health policy]. -[api health policy]: https://datafusion.apache.org/library-user-guide/api-health.html \ No newline at end of file +[api health policy]: https://datafusion.apache.org/library-user-guide/api-health.html diff --git a/docs/source/library-user-guide/api-health.md b/docs/source/library-user-guide/api-health.md index 7e13a6d49d4e..946281337552 100644 --- a/docs/source/library-user-guide/api-health.md +++ b/docs/source/library-user-guide/api-health.md @@ -28,9 +28,9 @@ APIs to give users time to adjust to the changes. ## Breaking Changes -In general, a function is part of the public API if it appears on the [docs.rs page] +In general, a function is part of the public API if it appears on the [docs.rs page] -Breaking public API changes are those that *require* users to change their code +Breaking public API changes are those that _require_ users to change their code for it to compile, and are listed as "Major Changes" in the [SemVer Compatibility Section of the cargo book]. Common examples of breaking changes: @@ -42,17 +42,17 @@ When making breaking public API changes, please add the `api-change` label to the PR so we can highlight the changes in the release notes. [docs.rs page]: https://docs.rs/datafusion/latest/datafusion/index.html -[SemVer Compatibility Section of the cargo book]: https://doc.rust-lang.org/cargo/reference/semver.html#change-categories +[semver compatibility section of the cargo book]: https://doc.rust-lang.org/cargo/reference/semver.html#change-categories ## Deprecation Policy When deprecating a method: -- Mark the API as deprecated using `#[deprecated`] and specify the exact DataFusion version in which it was deprecated +- Mark the API as deprecated using `#[deprecated`] and specify the exact DataFusion 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 after the -deprecation PR is merged. For example, if the next scheduled release `41.0.0`, +deprecation PR is merged. For example, if the next scheduled release `41.0.0`, and a method is deprecated in a PR, the deprecated version will be `41.0.0`. API deprecation example: From 38aa52c792653295a9dc70f7da3622001cdb4886 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Tue, 10 Dec 2024 05:57:59 -0500 Subject: [PATCH 3/7] Update docs/source/library-user-guide/api-health.md Co-authored-by: Jonah Gao --- docs/source/library-user-guide/api-health.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/library-user-guide/api-health.md b/docs/source/library-user-guide/api-health.md index 946281337552..313617bf6f7f 100644 --- a/docs/source/library-user-guide/api-health.md +++ b/docs/source/library-user-guide/api-health.md @@ -48,7 +48,7 @@ the PR so we can highlight the changes in the release notes. When deprecating a method: -- Mark the API as deprecated using `#[deprecated`] and specify the exact DataFusion version in which it was deprecated +- Mark the API as deprecated using `#[deprecated]` and specify the exact DataFusion 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 after the From bb12c9416c439f3a0596ad6730a58f8eefe35d84 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Fri, 13 Dec 2024 12:44:40 -0500 Subject: [PATCH 4/7] Add version guidance and make more copy/paste friendly --- docs/source/library-user-guide/api-health.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/docs/source/library-user-guide/api-health.md b/docs/source/library-user-guide/api-health.md index 313617bf6f7f..ad591f394573 100644 --- a/docs/source/library-user-guide/api-health.md +++ b/docs/source/library-user-guide/api-health.md @@ -51,11 +51,19 @@ When deprecating a method: - Mark the API as deprecated using `#[deprecated]` and specify the exact DataFusion 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 after the -deprecation PR is merged. For example, if the next scheduled release `41.0.0`, -and a method is deprecated in a PR, the deprecated version will be `41.0.0`. +The deprecated version is the next version which contains the deprecation. For +example, if the current version listed in [`Cargo.toml`] is `43.0.0` then the next +version will be `44.0.0`. -API deprecation example: +[`Cargo.toml`]: https://github.com/apache/datafusion/blob/main/Cargo.toml + +To mark the API as deprecated, use the `#[deprecated]` attribute like this: + +```rust + #[deprecated(since = "XXX", note = "What new API the user should use?")] +``` + +For example: ```rust #[deprecated(since = "41.0.0", note = "Use SessionStateBuilder")] From 5e221a5537b7fd9095794bbff6eec83c11b50f54 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Fri, 13 Dec 2024 12:45:45 -0500 Subject: [PATCH 5/7] prettier --- docs/source/library-user-guide/api-health.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/library-user-guide/api-health.md b/docs/source/library-user-guide/api-health.md index ad591f394573..3e684516d16f 100644 --- a/docs/source/library-user-guide/api-health.md +++ b/docs/source/library-user-guide/api-health.md @@ -55,7 +55,7 @@ The deprecated version is the next version which contains the deprecation. For example, if the current version listed in [`Cargo.toml`] is `43.0.0` then the next version will be `44.0.0`. -[`Cargo.toml`]: https://github.com/apache/datafusion/blob/main/Cargo.toml +[`cargo.toml`]: https://github.com/apache/datafusion/blob/main/Cargo.toml To mark the API as deprecated, use the `#[deprecated]` attribute like this: From 83a9e582cbe01684ca6a624747b77ed2e0ff6311 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Fri, 13 Dec 2024 12:46:36 -0500 Subject: [PATCH 6/7] better --- docs/source/library-user-guide/api-health.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/library-user-guide/api-health.md b/docs/source/library-user-guide/api-health.md index 3e684516d16f..25acf226aaef 100644 --- a/docs/source/library-user-guide/api-health.md +++ b/docs/source/library-user-guide/api-health.md @@ -60,7 +60,7 @@ version will be `44.0.0`. To mark the API as deprecated, use the `#[deprecated]` attribute like this: ```rust - #[deprecated(since = "XXX", note = "What new API the user should use?")] + #[deprecated(since = "...", note = "...")] ``` For example: From 1ba657e35940dbd5740ad6877ac06a4b524bcdd8 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Fri, 13 Dec 2024 12:48:13 -0500 Subject: [PATCH 7/7] rename to guidelines --- docs/source/library-user-guide/api-health.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/library-user-guide/api-health.md b/docs/source/library-user-guide/api-health.md index 25acf226aaef..46a894d4d5f7 100644 --- a/docs/source/library-user-guide/api-health.md +++ b/docs/source/library-user-guide/api-health.md @@ -44,7 +44,7 @@ the PR so we can highlight the changes in the release notes. [docs.rs page]: https://docs.rs/datafusion/latest/datafusion/index.html [semver compatibility section of the cargo book]: https://doc.rust-lang.org/cargo/reference/semver.html#change-categories -## Deprecation Policy +## Deprecation Guidelines When deprecating a method: