I don’t think an UPGRADING.md would be more prominent. I’ve never noticed an UPGRADING.md file in any project, and I’ve never looked for one. Just read the release notes.
I think CALCITE-7511 is a bug-fix, not a new feature — the current behavior is clearly not what anyone intended — so we should fix it. Every bug-fix theoretically is “breaking” if people had been relying on the broken behavior but it’s foolish to try to preserve or even apologize for the previous behavior. A simple line like “RelShuttle now dispatches a LogicalTableScan to visit(TableScan) rather than visit(RelNode)” is sufficient. > On May 14, 2026, at 1:25 PM, Venkatakrishnan Sowrirajan <[email protected]> > wrote: > > Hi Calcite devs, > > CALCITE-7511 / PR #4928 fixes a `RelShuttle` dispatch gap by adding > `accept(RelShuttle)` overrides and new `visit(X)` overloads on the > interface. This is source-incompatible for direct `RelShuttle` implementors > and behavior-incompatible for `RelShuttleImpl` subclasses that worked > around the gap with `instanceof` checks. > > In the review thread, @mihaibudiu <https://github.com/mihaibudiu> noted > Calcite's nominal semver would prohibit this in a minor release but that > postponing until a 2.0 isn't realistic; @xiedeyantu > <https://github.com/xiedeyantu> agreed and suggested documenting clearly in > the upgrade notes. CALCITE-7288 / PR #4620 raised similar concerns > previously. > > Is the `#### Breaking Changes` section in `history.md` the right place to > surface this for library users, or do we want something more prominent > (e.g., a dedicated UPGRADING.md, per-release migration guide)? > > Pointers > -------- > > - JIRA: https://issues.apache.org/jira/browse/CALCITE-7511 > - PR: https://github.com/apache/calcite/pull/4928 > - Prior related discussion: CALCITE-7288 / PR #4620 > > Thanks, > Venkat
