Update with a way back

Update one thing for a reason

An update can fix a bug or add a needed feature. It can also change the database, integrations, or license terms. “Upgrade everything” makes the result harder to understand and undo.

The sample pins its commerce backend and dependencies to reviewed versions. Check compatibility and third-party licensing before changing them. Use the update policy and supported versions in your delivered package.

1. Write an update card

Current release and dependency lockfile:
Proposed change and reason:
Files and services affected:
Database migration required? Yes / No / Unknown
Verified backup filename and restore-test date:
Separate test environment:
Expected result and checks:
Stop conditions:
Rollback steps and owner:

An unknown migration or rollback step is a reason to investigate before deployment.

2. Rehearse in a separate copy

Use the release’s supported way to create an isolated test environment. For this sample, isolation means a distinct Compose project, port, volumes, and settings. Simply copying the folder can still point commands at the original project’s resources; have the configuration reviewed before starting it.

Prefer synthetic data. Do not give a test copy access to live payment keys, customer email sending, or the production database.

Read the supported update procedure for this release. Review only
[SPECIFIC CHANGE]. First identify affected files, dependencies, license
changes, and any database migration. Explain the rollback for source
and data separately. Design a test copy with its own project name,
ports, volumes, and settings; prove it cannot touch the original.
Use synthetic data and test providers only. Run the documented type,
test, build, checkout, and restore checks in that copy. Show results
and remaining uncertainty. Do not switch production automatically.

3. Check behavior, not only the build

Open the homepage, product variants, cart, checkout, and Admin. Check an order through the supported test provider if the release includes one. Verify persistent media and email as applicable. Rehearse recovery after changes to data storage.

For this local sample, the documented engineering commands are:

npm run typecheck
npm test
npm --prefix backend run build

Run them one at a time in the test copy. Then use its documented startup, order verification, and restore check. They do not certify a live payment path that the sample does not implement.

4. Choose the right rollback

Change	Typical recovery action
Wording or CSS	Reverse the specific source change and rebuild.
Product wording in Admin	Restore the previous field value.
Application version without data changes	Return to the known compatible source and configuration.
Database migration	Use a reviewed migration/recovery procedure; reverting source alone may be insufficient.

If transactions occurred after an update, an old database restore can lose new orders. Keep the current database and reconcile the affected interval before any data replacement.

Ready when

You have a passing rehearsal, a matching backup, a scheduled owner for the change, and a tested recovery route. For a live shop, use a planned maintenance window and verify the deployed result afterward. Ask for separately scoped help if the change involves a major upgrade, migration, or new integration.