Definition changes: tagging, export, and deployment

RecordM tracks the evolution of a definition as a list of changes. Each time a definition is modified — a field added, a label renamed, a validation rule adjusted — RecordM records that modification as a discrete change alongside its author and timestamp.

This mechanism is not just an audit trail. It is the foundation for moving definitions between servers.

Tagging a change

A change can be given a tag: a short label that identifies it as part of a deliberate, named version. Untagged changes are local to the server; tagged changes are the ones that participate in the export and deployment cycle described here.

Tagging is done with cob-cli tagDefs, which reads solutions.yml to find the relevant definitions, fetches their untagged changes, and for each definition asks whether to tag all changes or choose a cutoff date up to which changes should be tagged. With the --all flag the command skips the prompts and tags everything.

When preparing a definition for deployment, a developer runs cob-cli tagDefs on the source server. That tag becomes the marker that downstream servers use to recognise this version of the changes.

Exporting changes

cob-cli updateFromServer retrieves the full changes history of each configured definition from the source server and writes it to others/solutionsData/<solution>/definitions/<definition_name>.json. The file contains every change — its id, date, author, tag, and the change payload itself — as a JSON array, one change per line for readability and clean diffs.

This file is what gets committed to the repository and later shipped to other environments.

Deploying to another server

When cob-cli deploy runs, it invokes cc-install on the destination server, which processes each definition by sending the exported changes to the server's merge endpoint. The server compares the incoming changes against its own existing history and produces a merge result.

If the definition does not yet exist on the destination, it is created and all changes are applied directly. No conflict is possible.

If the definition already exists, the server performs a merge. It keeps its own history intact and identifies which incoming changes are genuinely new by their tags. There are three outcomes:

• Noop. All incoming tagged changes are already present. Nothing is applied.
• Clean merge. The incoming changes are appended to the local history without conflict. The result is applied immediately.
• Rebase. The local history had diverged — changes were made directly on the destination server after the last synchronisation. The server reapplies those local changes on top of the incoming ones, producing a rebased history. The last change in the result carries no tag, signalling that a rebase occurred. In interactive mode the operator is asked to confirm before the result is applied; in batch mode the deployment is aborted so the situation can be reviewed.

Why tags matter

Tags are what make the merge algorithm safe. Without them, the server would have no way to distinguish a change that is already applied from one that is genuinely new, and every import would risk duplicating history. The tag on an incoming change is checked against existing tagged changes on the destination; a match means the change is already there and can be skipped.

Only tagged changes are exported. Untagged changes remain local to the source server and are never part of a deployment. Running cob-cli tagDefs before cob-cli updateFromServer is therefore what determines what actually gets deployed.

Summary

Source server
  └─ cob-cli tagDefs → tag untagged changes

cob-cli updateFromServer
  └─ Export changes history → others/solutionsData/.../definitions/<name>.json

Repository
  └─ Commit and ship the exported JSON

cob-cli deploy → cc-install on destination server
  ├─ New definition   → create and apply all changes directly
  └─ Existing definition → merge
       ├─ Noop          → already up to date, nothing to do
       ├─ Clean merge   → apply incoming changes
       └─ Rebase        → local changes rebased on top, confirm before applying