From 631408baefa79d80f2f7e59e8a6e22714312cc3e Mon Sep 17 00:00:00 2001
From: Oleks V <comphead@users.noreply.github.com>
Date: Thu, 24 Oct 2024 09:25:03 -0700
Subject: [PATCH] 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(+)
 create mode 100644 docs/source/library-user-guide/api-health.md

diff --git a/README.md b/README.md
index 30505d7ca132..bbbdf7133518 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 000000000000..943a370e8172
--- /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