Learning center

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.

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 codeWhat to checkUsual decision
Only code in this repositoryA search for the old name at the head commit, plus a buildDismiss 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 ruleDismiss. The go command's documentation 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 settingThe release that first shipped it, and your stability policy for that surfaceChange: 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 libraryWhat that language sees of the APITreat as external users of a released package

Then read your versioning policy. Under Semantic Versioning, the major version "MUST be incremented if any backward incompatible changes are introduced to the public API", and major version zero 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

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

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

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 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 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 recommends. When the old form survives as a deprecated alias, the next reviewer may flag it. The deprecation guide 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.

Start free with GitHub

Related reading