chore: Migration Guide

apache · Dec 19, 2024 · 3525a94 · 3525a94
1 parent 9f530dd
commit 3525a94
Show file tree

Hide file tree

Showing 3 changed files with 47 additions and 0 deletions.
diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md
@@ -0,0 +1,20 @@
+<!---
+  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.
+-->
+
+
diff --git a/docs/source/contributor-guide/index.md b/docs/source/contributor-guide/index.md
@@ -172,6 +172,7 @@ Some things to specifically check:
 
 1. Is the feature or fix covered sufficiently with tests (see the [Testing](testing.md) section)?
 2. Is the code clear, and fits the style of the existing codebase?
+3. Does the PR introduce a [breaking change](https://datafusion.apache.org/library-user-guide/api-health.html#breaking-changes)? If so the `api_change` Github badge needs to be added to the PR and migration documentation need to reflect changes according to [Migration Guidelines](https://datafusion.apache.org/library-user-guide/api-health.html#migration-guidelines)
 
 ## Performance Improvements
 

diff --git a/docs/source/library-user-guide/api-health.md b/docs/source/library-user-guide/api-health.md
@@ -69,3 +69,29 @@ For example:
 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
+
+
+## Migration Guidelines
+
+To ensure smooth upgrades and maintain application stability, the following guidelines must be followed for changes involving: 
+- Public API changes
+- Introducing deprecated methods
+- Removal of obsolete methods
+
+Highlight all breaking changes, deprecated methods, and obsolete methods in the [migration guide](../../../MIGRATION_GUIDE.md).
+
+### Migration Document Requirements:
+
+For each upgrade, append a section in [migration guide](../../../MIGRATION_GUIDE.md) outlining the following:
+
+#### Breaking Changes:
+- Describe all changes that break backward compatibility.
+- Provide detailed steps to migrate from old to new APIs.
+
+#### Deprecations:
+- List all deprecated methods and expected removal timelines.
+- Provide alternative methods or workarounds.
+
+#### Removals:
+- List all methods or APIs that are removed in the current release.
+- Suggest migration paths for impacted functionalities