findepi commented on code in PR #13849: URL: https://github.com/apache/datafusion/pull/13849#discussion_r1893873359
########## docs/source/library-user-guide/api-health.md: ########## @@ -69,3 +69,32 @@ 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 should 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 Review Comment: ouch, unless automated, we won't deprecate any code and won't remove and obsolete stuff. let's not do this ########## docs/source/library-user-guide/api-health.md: ########## @@ -69,3 +69,32 @@ 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 should be followed for changes involving: + +- Public API changes +- Introducing deprecated methods Review Comment: This should not involve any additional migration guide. I.e. this is automatic (unless the deprecated method is no longer correct to call; in such case we should remove it instead of deprecating, or fix it) ########## docs/source/library-user-guide/api-health.md: ########## @@ -69,3 +69,32 @@ 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 should 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: Review Comment: will we have merge conflicts there often? ########## docs/source/library-user-guide/api-health.md: ########## @@ -69,3 +69,32 @@ 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 Review Comment: > I personally don't think the last two items are worth documenting agreed > But one pros for documenting it in migration plan is the user is able to identify amount of migration work needed just by looking into the guide for a specific version. otoh it adds burden for development, and sets wrong incentives, discouraging from deprecating methods and removing old code If this is indeed useful, let's maybe automate pulling of new deprecations, rather than impose a new tax ########## docs/source/library-user-guide/api-health.md: ########## @@ -69,3 +69,32 @@ 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 should be followed for changes involving: + +- Public API changes Review Comment: we should say what consistutes a public api change - removal of a public function - signature change of a public function - semantic changes if a public funciton - new method in a public trait that has no default impl - new required traits of a public trait (eg requiring a Foo to be Sync) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: github-unsubscr...@datafusion.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org --------------------------------------------------------------------- To unsubscribe, e-mail: github-unsubscr...@datafusion.apache.org For additional commands, e-mail: github-h...@datafusion.apache.org
