Versioning and migrations

Releases

@bison-lab/fonts, @bison-lab/tokens, @bison-lab/ui, @bison-lab/admin-ui, @bison-lab/tailwind-preset, @bison-lab/create-theme, @bison-lab/payload-blocks and @bison-lab/payload-core are a linked group: a release that touches one bumps the others that changed to the same version, and leaves untouched packages alone. A released member bumps from the highest version anywhere in the group, not from its own, so a package can skip numbers.

@bison-lab/payload-blocks names @bison-lab/ui as a peer on a caret range of the current major. A minor of ui does not force a major of payload-blocks; only a major that leaves the declared range does.

@bison-lab/auth and @bison-lab/auth-prisma sit outside the group and version independently. They are not part of this guide.

A field change is a schema change

Every block field is a column in every consuming site. When a release changes one, its changelog says run payload migrate:create. Treat that line as part of the upgrade:

pnpm add @bison-lab/payload-blocks@latest @bison-lab/payload-core@latest
pnpm payload generate:types
pnpm payload generate:importmap
pnpm payload migrate:create

The same holds for noIndexField, the SEO plugin’s own fields, the Theme Global, Roles, Features, Admin nav, Header and Footer, Pages slug lock, Redirects, and the brand-assets collection in @bison-lab/payload-core.

What stays compatible

• A row saved against a block that has since left the config is dropped by RenderBlocks, not rendered broken.
• A site that forgets generate:importmap gets a logged miss and an empty field where the custom one should be (the array field, the link picker, Header items, Theme fields), not a crash; the stock field does not come back until the entry exists.
• Row types are structural and optional-and-nullable, so a site’s regenerated types keep assigning to them.