This is an automated email from the ASF dual-hosted git repository.
comphead pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/datafusion.git
The following commit(s) were added to refs/heads/main by this push:
new 631408baef Documentation: Add API deprecation policy (#13083)
631408baef is described below
commit 631408baefa79d80f2f7e59e8a6e22714312cc3e
Author: Oleks V <[email protected]>
AuthorDate: Thu Oct 24 09:25:03 2024 -0700
Documentation: Add API deprecation policy (#13083)
* Documentation: Add API deprecation policy
---
README.md | 5 ++++
docs/source/library-user-guide/api-health.md | 37 ++++++++++++++++++++++++++++
2 files changed, 42 insertions(+)
diff --git a/README.md b/README.md
index 30505d7ca1..bbbdf71335 100644
--- a/README.md
+++ b/README.md
@@ -134,3 +134,8 @@ For example, given the releases `1.78.0`, `1.79.0`,
`1.80.0`, `1.80.1` and `1.81
If a hotfix is released for the minimum supported Rust version (MSRV), the
MSRV will be the minor version with all hotfixes, even if it surpasses the
four-month window.
We enforce this 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
+
+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](docs/source/library-user-guide/api-health.md), ensuring the API is
stable and healthy.
diff --git a/docs/source/library-user-guide/api-health.md
b/docs/source/library-user-guide/api-health.md
new file mode 100644
index 0000000000..943a370e81
--- /dev/null
+++ b/docs/source/library-user-guide/api-health.md
@@ -0,0 +1,37 @@
+<!---
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# API health policy
+
+To maintain API health, developers must track and properly deprecate outdated
methods.
+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
+
+API deprecation example:
+
+```rust
+ #[deprecated(since = "41.0.0", note = "Use SessionStateBuilder")]
+ pub fn new_with_config_rt(config: SessionConfig, runtime: Arc<RuntimeEnv>)
-> Self
+```
+
+Deprecated methods will remain in the codebase for a period of 6 major
versions or 6 months, whichever is longer, to provide users ample time to
transition away from them.
+
+Please refer to [DataFusion
releases](https://crates.io/crates/datafusion/versions) to plan ahead API
migration
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
