findepi commented on code in PR #13701: URL: https://github.com/apache/datafusion/pull/13701#discussion_r1877921868
########## docs/source/library-user-guide/api-health.md: ########## @@ -19,11 +19,41 @@ # API health policy -To maintain API health, developers must track and properly deprecate outdated methods. +DataFusion is used extensively as a library and has a large public API, thus it +is important that the API is well maintained. In general, we try to minimize +breaking API changes, but they are sometimes necessary. + +When possible, rather than making breaking API changes, we prefer to deprecate +APIs to give users time to adjust to the changes. + +## Breaking Changes + +In general, a function is part of the public API if it appears on the [docs.rs page] + +Breaking public API changes are those that _require_ users to change their code +for it to compile, and are listed as "Major Changes" in the [SemVer Review Comment: Not "to compile" but rather "to compile and execute" for example replacing the function body with a `todo!()` is also a breaking change, even though it does not affect the compile time. See https://github.com/apache/datafusion/issues/13525#issuecomment-2496023457 -- we should not motivate people to avoid compile-time breakages as this may come at the cost of harder to find runtime-breakages (as witnessed in https://github.com/apache/datafusion/pull/13708#discussion_r1877895988) -- 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
