Deprecations

Sometimes a name in a published package turns out to be wrong — it promises one thing and does another, or a better shape replaces it. Forge does not rename it under you. It deprecates it, and a deprecation is a promise with a date on it.

The policy

A deprecated name survives at least one whole version series.

• Deprecated in the first release of a series (v0.4.0), it works in every v0.4.x release and is gone in v0.5.
• Deprecated in an intermediate release (v0.3.3, v0.4.3), the series it was deprecated in is no longer whole, so it also lives the whole next series: deprecated in v0.3.3 it is gone in v0.5; deprecated in v0.4.3, in v0.6.

Deprecated in	Still works in	Removed in
v0.4.0	every v0.4.x	v0.5
v0.3.3	v0.3.3 onwards, every v0.4.x	v0.5
v0.4.3	v0.4.3 onwards, every v0.5.x	v0.6

Intermediate releases are normal — several of them per series. If you pin an image and skip every one of them, you still pass through some release of a whole series that warns before the release that removes the name. Nothing is removed in an intermediate release. (From v1.0 on, the series is the major version.)

Where you see it

• In your editor. The export carries @deprecated, so the call site is struck through, and the tag names the replacement and the version that removes it.
• In development. The first time the old name runs, the process prints one warning naming the replacement and the removal version. Once per process — never once per call — and never in production.
• In the changelog of the package. Every deprecation has a Deprecated entry in the CHANGELOG.md that travels inside the package’s tarball, with a before/after of the migration, and the release notes collect it.
• Here. The table below lists every deprecation that is still live.

Live deprecations

Name	Package	Use instead	Deprecated in	Removed in
coverMediaOf	@forgeco/storefront-kit (/sku)	shownMediaOf — or coverImageOf for the cover itself	v0.3.3	v0.5

coverMediaOf. The name says “the cover” and it returns the list of media the product shows, so every caller wrapped it to get the cover. shownMediaOf is the same list under an honest name, and coverImageOf is the wrapper:

// before
const cover = coverOf(coverMediaOf(product));
const gallery = coverMediaOf(product);

// after
const cover = coverImageOf(product);
const gallery = shownMediaOf(product);

Names inside an app’s block

The stable names a store restyles an app’s block by (data-part, described under Apps and extensions) follow the same policy with the same arithmetic. A part on its way out is declared { name, deprecated: { deprecated_in, removed_in } } in the app’s manifest (deprecated_in is the release, e.g. "v0.3.3"; removed_in the series the rule above gives, e.g. "v0.5"), keeps rendering until then, and leaves in removed_in. No part is deprecated today.

When the removal comes

The release that removes a name says so in its changelog, under Removed. If your storefront still calls it, your build stops compiling at that call — which is why the warning and the strike-through come at least a whole series earlier. Migrating is a rename; do it whenever you next touch the file.