Learning center

Run a suggested API on the oldest version you support

When a reviewer suggests a method, option or flag, treat the suggestion as untested code. Find the API in the documentation or source of the version you pin, then run the suggested line on the oldest version you support. If it is missing there, dismiss the suggestion and cite the version note. If it exists but behaves differently, treat it as a behavior change that needs a test before it lands.

Know which version is "in use"#

A suggested API can fail in three ways, and only the first is pure invention:

  1. It exists in no version. The name is plausible, but no documentation or source mentions it.
  2. It exists, but only in releases newer than the ones you support. The suggestion matches a recent release, and your lockfile, toolchain file or test matrix names an older one.
  3. It exists in every version you support, but it does something slightly different from the code it replaces.

The second case is easy to miss, because the API is real and its documentation looks authoritative. "In use" means every version your project promises to run on: the oldest Python in requires-python and the CI matrix, the rust-version in Cargo.toml, the engines range in package.json, the module version in go.mod. A suggestion has to work on all of them.

Run the suggestion where it has to work#

A fictional example: a Python service declares requires-python = ">=3.11" and tests on 3.11, 3.12 and 3.13. It splits rows into fixed-size chunks with slicing:

def chunks(rows, size):
    return [rows[i:i + size] for i in range(0, len(rows), size)]

A reviewer suggests the standard library instead, with a flag that sounds like extra safety:

from itertools import batched

def chunks(rows, size):
    return list(batched(rows, size, strict=True))

I ran both versions with print(chunks(list(range(7)), 3)) on Python 3.11, 3.12 and 3.13 interpreters. The original prints [[0, 1, 2], [3, 4, 5], [6]] on all three. The suggestion fails differently on each:

PythonOutput of the suggested code
3.11ImportError: cannot import name 'batched' from 'itertools' (unknown location)
3.12TypeError: batched() takes at most 2 arguments (3 given)
3.13ValueError: batched(): incomplete batch

The documentation explains all three. Python's itertools.batched entry says "Added in version 3.12" and "Changed in version 3.13: Added the strict option." It also says that with strict true, batched "will raise a ValueError if the final batch is shorter than n." inspect.signature(itertools.batched) agrees: it prints (iterable, n) on 3.12 and (iterable, n, *, strict=False) on 3.13.

Even without strict, the suggestion would not have been a drop-in replacement. On 3.12 and 3.13, list(batched(list(range(7)), 3)) prints [(0, 1, 2), (3, 4, 5), (6,)]: tuples where the original returned lists, which matters to any caller that appends to a chunk.

This suggestion deserves a dismissal with the version note as the reason. Adopting it later, once the floor reaches 3.13, would need a decision about short final batches and a test for the tuple type, not a one-line swap.

Find the API before you run it#

Running the suggestion is the strongest check. Reading the API at the right version is faster, and it explains what a run shows:

EcosystemWhere to look at the pinned version
PythonThe documentation's "Added in version" and "Changed in version" notes, and inspect.signature on the oldest interpreter
RustThe item's #[stable(feature = ..., since = ...)] attribute in the source at your rust-version tag, or a build with that toolchain
TypeScript and JavaScriptThe .d.ts files of the installed version in node_modules, and your lib setting in tsconfig.json
Gogo doc for the symbol, inside the module, which reads the version go.mod requires

A symbol that appears in a release's source can still be unusable there. In Rust's standard library at the 1.91.0 tag, AtomicUsize::try_update is present but marked #[unstable(...)], so stable 1.91 cannot call it. It became stable in 1.95.0. The deprecation guide follows a real pull request that hit exactly that gap.

Decide from what you found#

What you foundDecision
No documentation or source mentions the API in any versionDismiss as nonexistent, saying where you looked
The API exists only in versions newer than your floorDismiss, citing the version note. If the API is worth adopting, open an issue tied to raising the floor
The API exists at your floor, but an option or argument does notDismiss the option, or adapt the suggestion to the floor's signature and run it
The API exists at every supported version but behaves differentlyTreat as a behavior change: add a test that pins the current behavior, then decide
The API exists at every supported version and the test passes on the oldestApply it

The same check works in reverse. A reviewer that says a method or version your code uses does not exist is making a claim about a specific release, which the same sources settle. The dependency guide follows a real thread where a bot called three build-tool versions "hallucinated" and the registry showed that at least two of them existed.

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