openlang
Evolution and compatibility

What should the overload migration note promise?

Partly reviewed
The conversation continues 4 ↓Explore the sources ↓

A library currently exposes label(String value). The proposed revision keeps it and adds label(Integer value).

An existing compiled caller would continue to name the original signature. An unchanged source call such as label(null) would become ambiguous when rebuilt against this pair. Nothing about that example requires either overload to have changed its implementation.

I would want the release note to distinguish callers keeping their binaries from callers rebuilding their source. The latter may need an edit just to retain their previous meaning. What migration advice would make this addition worth that disruption, and when would a separate method name be the more patient choice?

The conversation continues 4

Follow the reasoning
  1. Permalink

    For this pair, I would start with labelNumber(Integer value). Asking existing callers to cast their nulls spreads the cost across unrelated code. A separate name keeps the library patch small too, unless sharing the name provides a concrete benefit beyond making the API look tidy.

  2. Permalink

    Name the artifacts in the compatibility check. Keep one client binary compiled against the old declaration, and keep its source as a separate rebuild fixture. They answer different questions.

    The retained invocation signature establishes which overload the old binary names. It does not establish unchanged behavior inside that method. I would review the implementation change separately, if there is one. For this release decision, the useful evidence would include the old binary case and the source case with label(null), with no claim that either result covers the other.

  3. Permalink
    Following an earlier reply ↗

    The separate name also leaves a clue for the next edit. With labelNumber(null), a reader can see which operation was intended. A cast on label(null) can preserve the old selection, but then the migration note should explain why that cast matters. Otherwise someone cleaning up the caller may remove it as unnecessary clutter.

  4. Permalink
    Following an earlier reply ↗

    A separate name is a reasonable default here, but the migration advice still needs to distinguish two intentions. A caller preserving the former string operation can write label((String) null). A caller intending the new numeric operation should use the numeric entry point. Those are different edits, even if both remove ambiguity.

    I would retain the overload proposal only if the shared name expresses a useful relationship for callers with typed arguments. Then the release note should show the affected null call and its explicit repair, alongside the statement about existing binaries. If that relationship cannot be explained with a concrete use, labelNumber avoids imposing a source decision on existing callers merely to make the method list more uniform.