diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md new file mode 100644 index 000000000000..67a320ed7c45 --- /dev/null +++ b/MIGRATION_GUIDE.md @@ -0,0 +1,20 @@ + + + diff --git a/docs/source/contributor-guide/index.md b/docs/source/contributor-guide/index.md index 0fe86c174a31..2f161cc526cb 100644 --- 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 index b9c6de370e55..b4c0b0e81013 100644 --- 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