---
title: "Answer a breaking-change comment by naming the callers | Proofline"
description: "A reviewer that says your change breaks callers is right when a caller you promised compatibility to will stop compiling or behave differently."
url: https://proofline.sh/learn/ai-review-breaking-change-comment/
---

[Learning center](/learn/)

# Answer a breaking-change comment by naming the callers

A reviewer that says your change breaks callers is right when a caller you promised compatibility to will stop compiling or behave differently. Find those callers first. If every one is inside the pull request and updated, dismiss the comment with the search that shows it. If they are outside, keep a compatibility path or release the break under a major version with a changelog entry.

Code review The Proofline team November 22, 2026 4 min read

## Find out who the callers are

A breaking-change comment makes two claims at once: that the old signature or name is gone, and that someone still depends on it. The first is usually true, because the diff shows it. The second needs evidence the bot rarely has, so collect it yourself:

| Who can call the changed code | What to check | Usual decision |
| --- | --- | --- |
| Only code in this repository | A search for the old name at the head commit, plus a build | Dismiss with the search, if it finds nothing outside the diff |
| Code that the language prevents from importing it, such as a Go package under `internal/` | The language or tool rule | Dismiss. The [go command's documentation](https://pkg.go.dev/cmd/go) says code below a directory named `internal` "is importable only by code that shares the same import path above the internal directory" |
| Users of a released package or a documented setting | The release that first shipped it, and your stability policy for that surface | Change: add an alias or a deprecation path, or ship the break in a major release |
| Callers in another language, such as Java callers of a Kotlin library | What that language sees of the API | Treat as external users of a released package |

Then read your versioning policy. Under [Semantic Versioning](https://semver.org/#spec-item-8), the major version "MUST be incremented if any backward incompatible changes are introduced to the public API", and [major version zero](https://semver.org/#spec-item-4) makes no stability promise at all. Many projects publish narrower rules for parts of their API, and those rules decide what a break costs.

## A rename with released users

In August 2026, a Ray pull request renamed the `DataContext` setting `hash_shuffle_compression` to `shuffle_compression`. Gemini Code Assist's review asked for two things: "falling back to the old environment variable `RAY_DATA_HASH_SHUFFLE_COMPRESSION` if the new one is not set", and "providing deprecated property getters/setters for `hash_shuffle_compression` on `DataContext` to prevent breaking changes for programmatic users." [Review](https://github.com/ray-project/ray/pull/65590#pullrequestreview-4972750852)

Whether anyone could depend on the old name is a matter of release history. I fetched `python/ray/data/context.py` at Ray's release tags: the setting is absent at `ray-2.56.0` and present at `ray-2.57.0` and `ray-2.58.0`, so users of two published releases could have set it. `DataContext` carries Ray's `@DeveloperAPI` annotation, whose docstring says such interfaces "may change across minor Ray releases". Ray's policy allowed the break. The comment was still right that it would break someone.

The author's next commit, made the same day, was titled "\[Data\] Keep `hash_shuffle_compression` as a deprecated alias". The merged diff turns the old name into a property that warns with `DeprecationWarning` and forwards to the new field, keeps reading the old environment variable when the new one is unset, and adds `test_hash_shuffle_compression_alias`, which asserts both paths and that the warning is attributed to the caller's file. The pull request merged on 9 September 2026. [Pull request](https://github.com/ray-project/ray/pull/65590)

So this comment deserved a code change and a test. A comment like it deserves one whenever the old name has shipped and keeping it costs a few lines.

## A break the authors had already planned

A Firebase Android SDK pull request in September 2026 removed overloads that existed only for binary compatibility, folding a two-argument `DataConnectSettings` constructor and a `copy()` overload into versions where `cacheSettings` has a default value. Gemini Code Assist's review said "removing these explicit overloads breaks Java compatibility" and recommended applying `@JvmOverloads` to the constructor and the `copy` function. [Review](https://github.com/firebase/firebase-android-sdk/pull/8605#pullrequestreview-5217275135)

On the facts, the bot was right. Kotlin's documentation says a function with default parameter values is "visible in Java only as a full signature, with all parameters present" unless you add `@JvmOverloads`. It also notes that a class whose constructor parameters all have defaults gets a public no-argument constructor. [Calling Kotlin from Java](https://kotlinlang.org/docs/java-to-kotlin-interop.html#overloads-generation) A Java caller that wrote `new DataConnectSettings(host, sslEnabled)` loses that constructor. I read the documentation and the diff. I did not compile a Java caller against the new release.

The authors had already decided to accept the break. The deleted code carried comments beginning `TODO(BreakingChange)`, and the description says the changes "are source-compatible for typical Kotlin callers, but they are binary-breaking changes," "hence the major version bump to 18.0.0." [Description](https://github.com/firebase/firebase-android-sdk/pull/8605#issue-5468781267) At the merge commit, the module's `gradle.properties` reads `version=18.0.0` with `latestReleasedVersion=17.4.0`, and the changelog lists "Cleaned up overloads in QueryRef and DataConnectSettings." The pull request merged on 21 September 2026 without `@JvmOverloads`.

That comment was correct, and declining its fix was also correct, because the release that carries the break is a major version with a changelog entry. A sound reply points to both, so anyone reading the thread later knows the break was deliberate.

## Write the answer the comment needs

For a breaking-change comment, the reply should name the callers and the policy:

1.  Search for the old name at the head commit, then build. If nothing outside the diff uses it and the surface is not published, dismiss with the search command and its empty result.
2.  If the surface is published, find the first release that contained it. A name that never shipped can change freely.
3.  If it shipped, either keep the old form as a deprecated alias with a test for it, or point to the major version and the changelog entry that announce the break.

If you defer the alias, open a follow-up issue tied to the release that will carry the break, and put its link in the dismissal, so the thread records the reason the way the [guide to dismissed findings](/learn/reconstruct-dismissed-review-finding/) recommends. When the old form survives as a deprecated alias, the next reviewer may flag it. The [deprecation guide](/learn/ai-review-deprecated-api-comment/) covers how to answer that comment.

## One month of free code review.

New organizations get one calendar month of hosted code review for private and public GitHub repositories. No card or cloud connection required. [Eligibility and fair-use terms](/free-code-review/).

[Start free with GitHub](https://proofline.sh/orgs/plan?offer=free_month)

## Related reading

-   ### [Who relies on the old default? Decide a changed-default comment](/learn/ai-review-default-value-change-comment/)
    
    Code review The Proofline team November 22, 2026 4 min read
    
-   ### [Check a deprecation claim against the version you actually pin](/learn/ai-review-deprecated-api-comment/)
    
    Code review The Proofline team November 22, 2026 5 min read
