Upgrade guides

An Evolve upgrade is a version change in your catalog, plus whatever the release notes ask you to change in your own code. This page has the steps, and a page per month with every breaking change and what to do about it. For how Evolve versions its packages and which code is yours to keep up to date, see Your code and ours.

Upgrade your project

Find what you run. Your Evolve versions are the @evolve-framework/* and @evolve-storefront/* entries in the catalog: of pnpm-workspace.yaml.
Find the new versions. pnpm view @evolve-framework/commercetools version prints the latest release of a package.
Read the notes in between. For each package, read the notes of every version between yours and the new one. Most packages are below 1.0.0, so a minor version can be breaking. Search the notes for **Breaking change: each one says what to change. They are also all in the months below, newest first.
Raise the versions together. Take every @evolve-framework/* package to the same release, and every @evolve-storefront/* package too. Evolve packages are peer dependencies of each other. One you leave behind, such as a payment provider, can pull in a second copy of @evolve-framework/commercetools, and the types of two copies do not match.
Install with pnpm install. A peer dependency warning means a version is outside the range another package asks for. After the install, each package’s notes are also in node_modules/<package>/CHANGELOG.md.
Make the changes the breaking change notes ask for.
Check the result:
```
pnpm codegen   # regenerate the GraphQL types and the supergraph
pnpm check     # format, typecheck, and lint
pnpm test
```
pnpm codegen fails on a storefront query that selects a field the new schema no longer has, and pnpm check on code that uses a removed export. Then run the project and place an order.
Deploy the services and the storefront together when the schema changed. A storefront query for a field that is gone fails against the new services.

The reference sites have a task for steps 2, 4, and 5:

task framework-update

It sets every @evolve-framework/* and @evolve-storefront/* entry in the catalog to the newest published version, and runs pnpm install and pnpm dedupe. Check what it picked before you commit: when a prerelease build is newer than the latest release it picks that one, so pin the release instead.

Upgrade the gateway

The GraphQL gateway is an image, not a package. Its tag is in your deploy config, and in docker-compose.yaml for local development. Your backend/graphql-gateway/router.config.yaml is a copy of the image’s own config, so it does not follow a new tag by itself. Compare the two when you change the tag:

docker run --rm --entrypoint cat \
  ghcr.io/evolve-platform/evolve-graphql-gateway:<tag> /app/router.config.yaml \
  | diff -u - backend/graphql-gateway/router.config.yaml

Only the blocks you added yourself should show up as a difference.

Projects that vendor the framework

If your project still has framework packages as source code under vendor/packages/, move to the registry packages first: pin them in the catalog, refer to them with catalog: instead of workspace:*, and remove the vendored copies.

Breaking changes by month

Each month lists the changes its releases marked as breaking, with what to change in your project, and any change to the supported browsers. Read every month between the release you run and the one you move to.