From e36e9b64f35352a302c8960fed2527ac61c46acf Mon Sep 17 00:00:00 2001 From: Adrian Garcia Badaracco <1755071+adriangb@users.noreply.github.com> Date: Thu, 30 Jul 2026 09:13:02 -0500 Subject: [PATCH] refactor: mark the ExecutionPlan proto dispatch traits as non-public API `ExecutionPlanEncode` / `ExecutionPlanDecode` are dispatch details of the `try_to_proto` / `try_from_proto` hooks, not extension points: they are defined in `datafusion-physical-plan`, implemented only by the converter adapters in `datafusion-proto`, and reached by plans exclusively through `ExecutionPlanEncodeCtx` / `ExecutionPlanDecodeCtx`. They are `pub` only because those adapters live in another crate. Nothing said so to the tooling, so every ctx capability the epic still has to add counts as a major breaking change. Mark both `#[doc(hidden)]`, which is what they already were in intent, and say why in their docs. `cargo-semver-checks` then treats later `encode_*` / `decode_*` additions as what they are: changes to something that was never public API. Co-Authored-By: Claude Opus 5 --- datafusion/physical-plan/src/proto.rs | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/datafusion/physical-plan/src/proto.rs b/datafusion/physical-plan/src/proto.rs index 1731203f6c767..f8fb4ea41e319 100644 --- a/datafusion/physical-plan/src/proto.rs +++ b/datafusion/physical-plan/src/proto.rs @@ -33,7 +33,8 @@ //! * [`ExecutionPlanEncode`] / [`ExecutionPlanDecode`] — internal dispatch //! traits, *defined* here but *implemented* in `datafusion-proto`, that the //! context types delegate to. This is the dependency inversion that keeps the -//! proto types flowing in one direction only. +//! proto types flowing in one direction only. They are `#[doc(hidden)]`: not +//! public API, `pub` only because their implementors live in another crate. //! //! `datafusion-physical-plan` depends on the pure prost types in //! `datafusion-proto-models` (feature `proto`), never on `datafusion-proto`. @@ -72,6 +73,11 @@ use crate::ExecutionPlan; /// /// Implemented by `datafusion-proto`. Plan authors never name this trait; they /// call methods on [`ExecutionPlanEncodeCtx`] instead. +/// +/// **Not public API.** `pub` only because the implementors live in another +/// crate; `#[doc(hidden)]` records that, so encoding primitives can be added +/// here as the serialization hooks grow without breaking downstream code. +#[doc(hidden)] pub trait ExecutionPlanEncode { /// Serialize a child execution plan (recursing through the central /// serializer, so the child's own `try_to_proto` hook is honored). @@ -97,6 +103,11 @@ pub trait ExecutionPlanEncode { /// /// Implemented by `datafusion-proto`. Plan authors never name this trait; they /// call methods on [`ExecutionPlanDecodeCtx`] instead. +/// +/// **Not public API.** `pub` only because the implementors live in another +/// crate; `#[doc(hidden)]` records that, so decoding primitives can be added +/// here as the serialization hooks grow without breaking downstream code. +#[doc(hidden)] pub trait ExecutionPlanDecode { /// Deserialize a child execution plan (recursing through the central /// deserializer, so the child's own `try_from_proto` is honored).