Deprecating and removing an API

A deprecation names the version it will be removed in, and that version is two minor versions ahead of the one in pyproject.toml. With 0.10.1.dev0 in the file, a deprecation written today names v0.12.0. Two rather than one, because the next minor version is usually close enough that a deprecation landing now would give nobody time to act on it.

The version goes in both the FutureWarning and the changelog line, next to what to use instead:

warnings.warn(
    "'es_key' is deprecated and will be removed in v0.12.0. Use 'metadata_key' instead.",
    FutureWarning,
    stacklevel=2,
)

Why a version and not a date

A version is something a reader can act on. Told that something goes in v0.12.0, they can pin neuroconv<0.12 and migrate on their own schedule. Told that it goes “on or after August 2027”, they have nothing to pin against, and nothing enforces the date either, so it is as easily missed as met.

Removing it

The removal happens at the minor version the warning names, never earlier and never in a patch release. Clearing the deprecations that have come due is a step of Release Process for Neuroconv.

Some older warnings still carry a date, worded “on or after <Month Year>”. Those are triggered by their date rather than by a version, since the date is the promise they shipped under, and they are being restated as versions.