alamb commented on code in PR #13849: URL: https://github.com/apache/datafusion/pull/13849#discussion_r1893171675
########## 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: Review Comment: Stylistically I would prefer to say this more gently "the following guidelines should be followeed" rather than must. Mostly because there is no way for us to enforce this policy other than pull request reviews However, I think that may just be a cultural hangup I have as I come from the US and the distinction may not be relevant for other contributors ########## 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: Review Comment: Maybe we can also explicitly say here "it is preferrable not to make breaking API changes and instead add new APis and deprecate existing ones in which case no migration guide is needed" That would perhaps also subtley incentivize people to avoid breaking changes 🤔 ########## 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 -- deprecated methods should have already been removed so there is no need for a contributor to try and document anything when removing them I would also like us to get more in the habit of deprecating rather than removing methods which will make the last item irrelevant. -- 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
