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 c55319e0b6 docs: Document the convention for internal public APIs
(#25495)
c55319e0b6 is described below
commit c55319e0b630568a4d52097df8feee1800b19b6a
Author: Yongting You <[email protected]>
AuthorDate: Tue Sep 22 04:17:41 2026 +0000
docs: Document the convention for internal public APIs (#25495)
## Which issue does this PR close?
<!--
We generally require a GitHub issue to be filed for all bug fixes and
enhancements and this helps us generate change logs for our releases.
You can link an issue to this PR using the GitHub syntax. For example
`Closes #123` indicates that this PR will close issue #123.
-->
- Closes #.
## Rationale for this change
<!--
Why are you proposing this change? If this is already explained clearly
in the issue then this section is not needed.
Explaining clearly why changes are proposed helps reviewers understand
your changes and offer better suggestions for fixes.
Please explain the problem you are trying to solve in terms of the
user-visible
behavior, rather than the implementation.
For example, "The code in `foo.rs` doesn't handle nulls" is a symptom of
the
implementation. "COUNT(DISTINCT) returns wrong results when the column
contains
nulls" is the user-visible problem.
-->
The purpose should be clear from the PR diff itself.
It is an existing convention, this PR document it in API policy.
There are other ~5 places have this pattern, I plan to make a follow-up
PR to update their comments.
## What changes are included in this PR?
<!--
There is no need to duplicate the description in the issue here, but it
is sometimes worth providing a summary of the individual changes in this
PR.
-->
## What is the testing strategy for this PR?
<!--
We typically require tests for all PRs in order to:
1. Prevent the code from being accidentally broken by subsequent changes
2. Serve as another way to document the expected behavior of the code
Briefly describe how this PR is tested, and point to the specific tests
you added. For example: 'This new feature is covered by the
`sqllogictest` cases added in `foo.slt`'.
If this PR does not add tests, explain why. For example, if the change
is already covered by existing tests, please mention it.
You should also check the `codecov` bot reply on this PR to confirm the
changed code is exercised.
-->
## Are there any user-facing changes?
<!--
If there are user-facing changes then we may require documentation to be
updated before approving the PR.
If there are any breaking changes to public APIs, please add the `api
change` label.
-->
---
.../src/joins/hash_join/partitioned_hash_eval.rs | 8 +++---
docs/source/contributor-guide/api-health.md | 29 ++++++++++++++++++++++
2 files changed, 34 insertions(+), 3 deletions(-)
diff --git
a/datafusion/physical-plan/src/joins/hash_join/partitioned_hash_eval.rs
b/datafusion/physical-plan/src/joins/hash_join/partitioned_hash_eval.rs
index 98e8b2d2fc..82863c0802 100644
--- a/datafusion/physical-plan/src/joins/hash_join/partitioned_hash_eval.rs
+++ b/datafusion/physical-plan/src/joins/hash_join/partitioned_hash_eval.rs
@@ -293,9 +293,11 @@ impl HashTableLookupExpr {
/// * `random_state` - SeededRandomState for hashing
/// * `map` - Map to check membership (hash table or array map)
/// * `description` - Description for debugging
- /// # Note
- /// This is public for internal testing purposes only and is not
- /// guaranteed to be stable across versions.
+ ///
+ /// # Public Only for Internal Use:
+ /// `datafusion-proto` tests require this constructor, but it is not part
of
+ /// the supported public API.
+ #[doc(hidden)]
pub fn new(
on_columns: Vec<PhysicalExprRef>,
random_state: SeededRandomState,
diff --git a/docs/source/contributor-guide/api-health.md
b/docs/source/contributor-guide/api-health.md
index a20bc284cf..8737df280f 100644
--- a/docs/source/contributor-guide/api-health.md
+++ b/docs/source/contributor-guide/api-health.md
@@ -43,6 +43,35 @@ Examples of non-breaking changes include:
- Marking a function as deprecated (`#[deprecated]`)
- Adding a new function to a `trait` with a default implementation
+### DataFusion-internal Public APIs
+
+Some internal implementation details require `pub` visibility because they are
+shared across DataFusion crates. These APIs are not intended as downstream
+extension points. They are hidden from generated documentation and are not part
+of DataFusion's supported public API, so they may be changed or removed without
+notice or a deprecation period. Examples include:
+
+1. Test helpers.
+2. Operator APIs required by the optimizer to inspect or rewrite execution
plans
+ across crate boundaries.
+
+For APIs intended only for internal use, add `#[doc(hidden)]` and a doc comment
+section headed `# Public Only for Internal Use:`. Name the crate or component
+that requires access and explain why the API is not intended for downstream
use.
+For example:
+
+```txt
+impl HashTableLookupExpr {
+ /// ...
+ ///
+ /// # Public Only for Internal Use:
+ /// `datafusion-proto` tests require this constructor, but it is not part
of
+ /// the supported public API.
+ #[doc(hidden)]
+ pub fn new(...) {...}
+}
+```
+
### 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
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
