From 1393364100a286fc7909a233cb4f14df137327cf Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Fri, 13 Dec 2024 19:58:22 -0500 Subject: [PATCH 1/2] Improve deprecation guidelines more --- README.md | 6 +++--- docs/source/library-user-guide/api-health.md | 8 ++------ 2 files changed, 5 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 6ec6e92ea8c1..f199021d7d78 100644 --- a/README.md +++ b/README.md @@ -138,10 +138,10 @@ Note: If a Rust hotfix is released for the current MSRV, the MSRV will be update DataFusion enforces MSRV policy using a [MSRV CI Check](https://github.com/search?q=repo%3Aapache%2Fdatafusion+rust-version+language%3ATOML+path%3A%2F%5ECargo.toml%2F&type=code) -## DataFusion API evolution policy +## DataFusion API Evolution and Deprecation Guidelines 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]. +deprecate methods before removing them, according to the [deprecation guidelines]. -[api health policy]: https://datafusion.apache.org/library-user-guide/api-health.html +[deprecation guidelines]: 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 46a894d4d5f7..c1d85f0d0a1a 100644 --- a/docs/source/library-user-guide/api-health.md +++ b/docs/source/library-user-guide/api-health.md @@ -31,7 +31,7 @@ APIs to give users time to adjust to the 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 +for it to compile and execute, 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)`) @@ -57,11 +57,7 @@ version will be `44.0.0`. [`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 = "...", note = "...")] -``` +To mark the API as deprecated, use the `#[deprecated(since = "...", note = "...")]` attribute. For example: From 920174cf814b00c3e3f21458c6d87ec9b38f2a61 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Fri, 13 Dec 2024 19:58:46 -0500 Subject: [PATCH 2/2] 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 c1d85f0d0a1a..b9c6de370e55 100644 --- a/docs/source/library-user-guide/api-health.md +++ b/docs/source/library-user-guide/api-health.md @@ -57,7 +57,7 @@ version will be `44.0.0`. [`cargo.toml`]: https://github.com/apache/datafusion/blob/main/Cargo.toml -To mark the API as deprecated, use the `#[deprecated(since = "...", note = "...")]` attribute. +To mark the API as deprecated, use the `#[deprecated(since = "...", note = "...")]` attribute. For example: