From 3525a9491e5b00cb74a693fdb0d9a0b98d02e326 Mon Sep 17 00:00:00 2001 From: comphead Date: Thu, 19 Dec 2024 12:13:04 -0800 Subject: [PATCH 1/3] chore: Migration Guide --- MIGRATION_GUIDE.md | 20 +++++++++++++++ docs/source/contributor-guide/index.md | 1 + docs/source/library-user-guide/api-health.md | 26 ++++++++++++++++++++ 3 files changed, 47 insertions(+) create mode 100644 MIGRATION_GUIDE.md 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 From 74351d3437dec9aea8b0142f82760f9b2202366d Mon Sep 17 00:00:00 2001 From: comphead Date: Thu, 19 Dec 2024 12:17:30 -0800 Subject: [PATCH 2/3] chore: Migration Guide --- docs/source/library-user-guide/api-health.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/source/library-user-guide/api-health.md b/docs/source/library-user-guide/api-health.md index b4c0b0e81013..6e40b81c3e2e 100644 --- a/docs/source/library-user-guide/api-health.md +++ b/docs/source/library-user-guide/api-health.md @@ -70,10 +70,10 @@ Deprecated methods will remain in the codebase for a period of 6 major versions 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: +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 @@ -85,13 +85,16 @@ Highlight all breaking changes, deprecated methods, and obsolete methods in the 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 From c9671347fcff6cc34c31b2298584bf130d7a1ad4 Mon Sep 17 00:00:00 2001 From: comphead Date: Thu, 19 Dec 2024 15:35:27 -0800 Subject: [PATCH 3/3] chore: Migration Guide --- docs/source/contributor-guide/index.md | 2 +- docs/source/library-user-guide/api-health.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/contributor-guide/index.md b/docs/source/contributor-guide/index.md index 2f161cc526cb..db28c195a170 100644 --- a/docs/source/contributor-guide/index.md +++ b/docs/source/contributor-guide/index.md @@ -172,7 +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) +3. Does the PR introduce a [breaking change](https://datafusion.apache.org/library-user-guide/api-health.html#breaking-changes)? If so please follow the [breaking change policy](https://datafusion.apache.org/library-user-guide/api-health.html#breaking-changes) and migration documentation needs to be updated 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 6e40b81c3e2e..db18f248fed7 100644 --- a/docs/source/library-user-guide/api-health.md +++ b/docs/source/library-user-guide/api-health.md @@ -38,7 +38,7 @@ Compatibility Section of the cargo book]. Common examples of breaking changes: - Removing a `pub` function - Changing the return type of a function -When making breaking public API changes, please add the `api-change` label to +When making breaking public API changes, please add the `api change` label to the PR so we can highlight the changes in the release notes. [docs.rs page]: https://docs.rs/datafusion/latest/datafusion/index.html @@ -72,7 +72,7 @@ Please refer to [DataFusion releases](https://crates.io/crates/datafusion/versio ## Migration Guidelines -To ensure smooth upgrades and maintain application stability, the following guidelines must be followed for changes involving: +To ensure smooth upgrades and maintain application stability, the following guidelines should be followed for changes involving: - Public API changes - Introducing deprecated methods