Changing and Upgrading Open Mercato Code

A change can affect routes, events, permissions, stored data and generated files. Review those interfaces before upgrading the framework or publishing a module used by other teams.

On this page

Keep public names stable

A route, event name, feature identifier or dependency-injection key may have callers outside the file you are editing. Look for consumers before renaming it. Read the project’s compatibility policy and document the migration when an interface changes.

Architecture in practiceKeep the public contract while changing the implementation

Code that calls your modulePage · API route · subscriber

stable name + input format

Public contract

service.case.createSame command ID and required fields

Before the changeExisting implementation

After the changeNew implementation, existing callers still work

Example command name. A changed input or behavior may require a migration even when the name stays the same.

Code and documentation

BACKWARD_COMPATIBILITY.md

A useful change checklist

Change the source file and regenerate any derived registries.
Check old callers as well as the new behavior.
Include permission-denied, invalid-input and failed-provider cases in relevant tests.
Explain required configuration or data migration in the upgrade notes.

Code and documentation

generators/module-registry.ts · BACKWARD_COMPATIBILITY.md

Example: adding a required field

Suppose a service-case command starts requiring priority. Updating its form is only one part of the change: imports, event handlers and external API clients may still send the old payload. Existing database rows also lack the new value.

A staged migration can introduce an optional field with a deliberate default, populate existing rows and update callers before making it mandatory. If there is no safe default, reject the old payload with an actionable error and provide a migration path. The choice depends on the business meaning of the field.

Code and documentation

BACKWARD_COMPATIBILITY.md

Which changes reach other code?

Change	Who depends on it
Event name or payload	Subscribers, including queued work created before deployment. Keep readers compatible with older payloads during rollout.
Command ID, input or result	Routes, imports, automation and tools. Test their existing calls against the new implementation.
Permission identifier	Saved role configuration and guards. Renaming it can deny access to existing users.
Entity schema	Existing records, queries and deployment order. Include a database migration and a recovery plan.

Code and documentation

BACKWARD_COMPATIBILITY.md · events/factory.ts

AI tools that change data

AI tools that mutate data use preparation and confirmation stages. Keep the operation’s scope, preview and approval checks together when adding a tool. A natural-language request alone should not silently bypass the configured confirmation flow.

Code and documentation

lib/prepare-mutation.ts

Work on an application or contribute upstream?

Use the scripts and dependency versions from your application when building a custom feature. A contribution to the product repository must also follow its package rules and required checks. Record which environment you used when reporting a problem or sharing a reproducible example.

Code and documentation

BACKWARD_COMPATIBILITY.md

Sources

Open Mercato source used in these explanations