This is an automated email from the ASF dual-hosted git repository.
github-merge-queue[bot] pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/datafusion.git
The following commit(s) were added to refs/heads/main by this push:
new 70caf372a5 Add SQL as a category in breaking API change policy (#22179)
70caf372a5 is described below
commit 70caf372a54a088b4bcfd3b4479490f3388971d8
Author: Andrew Lamb <[email protected]>
AuthorDate: Wed May 20 11:20:37 2026 -0400
Add SQL as a category in breaking API change policy (#22179)
## Which issue does this PR close?
- Follow on to https://github.com/apache/datafusion/pull/21743
- Related to https://github.com/apache/datafusion/pull/22102
## Rationale for this change
As we have discovered, sometimes seemingly minor changes in SQL
semantics have caused non trivial downstream pain, for example the
recent changes to NULL semantics in `ANY/ALL`. See
-
https://github.com/apache/datafusion/pull/21743#issuecomment-4412252130
## What changes are included in this PR?
Add a note to the the API guide making it clear that changes to SQL
semantics are also API changes too and deserve extra attention.
## Are these changes tested?
By CI
## Are there any user-facing changes?
Clearer API docs
---
docs/source/contributor-guide/api-health.md | 46 ++++++++++++++++++++---------
1 file changed, 32 insertions(+), 14 deletions(-)
diff --git a/docs/source/contributor-guide/api-health.md
b/docs/source/contributor-guide/api-health.md
index f950c7cc0b..a20bc284cf 100644
--- a/docs/source/contributor-guide/api-health.md
+++ b/docs/source/contributor-guide/api-health.md
@@ -25,13 +25,13 @@ changes to avoid issues for downstream users.
## Breaking API Changes
-### What is the public API and what is a breaking API change?
+### What is the public Rust API and what is a breaking API change?
-In general, an item is part of the public API if it appears on the [docs.rs
page].
+An item is part of the public Rust 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 execute, and are listed as "Major Changes" in the [SemVer
-Compatibility Section of the Cargo Book]. Common examples of breaking changes
include:
+Breaking changes _require_ users to modify their code for it to compile and
+run, and are listed as "Major Changes" in the [SemVer Compatibility Section of
+the Cargo Book]. Common examples include:
- Adding new required parameters to a function (`foo(a: i32, b: i32)` ->
`foo(a: i32, b: i32, c: i32)`)
- Removing a `pub` function
@@ -43,6 +43,16 @@ Examples of non-breaking changes include:
- Marking a function as deprecated (`#[deprecated]`)
- Adding a new function to a `trait` with a default implementation
+### What is the public SQL API and what is a breaking SQL change?
+
+DataFusion is also used as a SQL engine, so changes to SQL semantics (the
+results returned for a given query) are a form of breaking change. Even with
+no Rust API change, altering the behavior of an existing SQL construct can
+silently break downstream applications, dashboards, and tests.
+
+We apply the same caution to SQL semantics changes as to Rust API changes:
+the benefit must be weighed against the cost of breaking downstream users.
+
### When to make breaking API changes?
When possible, we prefer to avoid making breaking API changes. One common way
to
@@ -54,22 +64,30 @@ change with the cost (impact on downstream users). It is
often frustrating for
downstream users to change their applications, and it is even more so if they
do not gain improved capabilities.
-Examples of good reasons for making a breaking API change include:
+Examples of good reasons for a breaking API or SQL change:
-- The change allows new use cases that were not possible before
-- The change significantly enables improved performance
+- It enables new use cases that were not possible before
+- It significantly improves performance
+- The previous behavior is clearly wrong (e.g. produces incorrect results)
-Examples of potentially weak reasons for making breaking API changes include:
+Examples of potentially weak reasons:
-- The change is an internal refactor to make DataFusion more consistent
-- The change is to remove an API that is not widely used but has not been
marked as deprecated
+- An internal refactor to make DataFusion more consistent
+- Removing an API that is not widely used but has not been marked as deprecated
+- Slightly improving compatibility with another database (for example,
+ PostgreSQL or DuckDB)
### What to do when making breaking API changes?
-When making breaking public API changes, please:
+When making breaking Rust API changes, please:
+
+1. Add the `api-change` label so the change is highlighted in the release
notes.
+2. Document non-trivial changes in the version-specific [Upgrade Guide].
-1. Add the `api-change` label to the PR so we can highlight the changes in the
release notes.
-2. Consider adding documentation to the version-specific [Upgrade Guide] if
the required changes are non-trivial.
+For breaking SQL changes, also describe the previous and new behavior in the PR
+description, ideally including example queries and results where appropriate.
+This makes review easier and helps downstream users discover the affected
+semantics.
[docs.rs page]: https://docs.rs/datafusion/latest/datafusion/index.html
[semver compatibility section of the cargo book]:
https://doc.rust-lang.org/cargo/reference/semver.html#change-categories
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
