Upgrading

What to do when you move between SPOC versions. Short on purpose: from 1.0 the stability contract means most upgrades need nothing from you, and when one does, the changelog entry says so in a sentence that starts "What a consumer must do."

The pin that matters

pip install "spoc>=1.0,<2"

A public name changes incompatibly only in a major release, after a completed deprecation cycle — so <2 is the whole promise. Pinning tighter buys nothing; pinning looser opts into the next major's breaks.

0.x to 1.0

Three changes can touch a 0.x project. All three fail loudly, so a missed one cannot pass silently.

1. meta= became metadata=. Registration used to spell the concept one way while the record spelled it another; one concept now carries one name at every surface. Rename the keyword at each call site:

-@model(meta=Meta(order_by="-created"))
+@model(metadata=Meta(order_by="-created"))

The old spelling is gone rather than deprecated — it went in the release that closed the pre-1.0 allowance. A missed site raises TypeError at import.

2. Regenerate your stub. spoc stubs --check reports a stub generated by a pre-1.0 release as stale. Regenerate it once:

spoc stubs

3. Nothing else. Everything importable from spoc on 0.8 imports from 1.0. If your project boots under spoc check, you are done.

Every later upgrade

The changelog is the migration guide. Each entry that asks anything of you carries a "What a consumer must do" paragraph; an entry without one is safe to take blind. Deprecations warn for a full deprecation cycle before a removal, and the error index stays current with every release — an unfamiliar error after an upgrade has a row there.