Publishing low-code configuration: versions, migrations and rollback

01 / One version number is not enough

The current version field identifies the supported configuration format. Changing a label, adding an optional field and changing a field unit can all happen within that format, but they have different compatibility consequences.

A persistent system should distinguish format version, stable form ID and immutable business revision. A stored record should carry enough information to identify the definition that interpreted it.

{
  "formatVersion": 1,
  "schemaId": "expense_request",
  "revision": 3,
  "rendererVersion": "1.2.0",
  "record": {
    "schemaRevision": 3,
    "values": {
      "amount": 120,
      "currency": "CNY"
    }
  }
}

This is a proposed record envelope, not the current demo schema. A renderer version records an implementation; it does not by itself guarantee backward compatibility.

02 / Classify changes by their data effect

• Label or ordering: often a presentation change, provided the field meaning is unchanged.
• Add an optional field: decide how older records without it are read; distinguish missing from an explicit zero or false.
• Make a field required or remove an option: existing records may no longer satisfy current rules. Decide whether to preserve historical validity or require a repair workflow.
• Change type, key or unit: require a mapping and loss analysis. Do not convert a string identifier such as 00123 into a number just because it looks numeric.

03 / Preview and publish are different operations

A possible workflow is draft → structural validation → dependency checks → preview → review → immutable revision → active-revision switch. Validation should finish before anything becomes active.

An editor should submit the base revision it edited. If another editor has already published a newer revision, reject the stale publish and show a comparison. Silent last-writer-wins can discard somebody else’s change.

A file hash can help identify the reviewed artifact; approval still depends on authorization and audit records. The system must not confuse matching bytes with an authorized release.

04 / Rehearse migrations before applying them

For a unit change from hours to minutes, specify the source revision, target revision, conversion, rounding policy and failure behavior. Run a dry pass on a copy and report records that cannot be transformed without a decision.

Track the revision or migration marker and make retries safe. A conversion blindly applied twice could multiply the value twice. Keep the original representation or a recoverable backup where required, and log which records were changed.

05 / A rollback does not rewind business data

Switching the active pointer back to revision 2 does not undo records created under revision 3 or recover a field that was already deleted. Before rollback, check whether the older renderer can read newer records and whether writes must be paused.

Prefer retaining immutable revisions and selecting the correct reader for historical records. When reverse migration is lossy, an explicit forward fix may be safer than pretending every change can be reversed.

06 / What AI changes, and what it does not

AI can propose a schema, field help text and tests. I would first treat the result as a draft, compare it with the supported format, and examine required fields, defaults, hidden-value policies and migrations. A plausible JSON file is not a reviewed business change.

For this project, the next useful exercise is a small versioned draft store with clear failure behavior. Calling it a complete low-code platform before persistence, permission and rollback are verified would hide the most important remaining work.

07 / Questions for a release review

• Can a historical record identify and load the definition it was created with?
• Does an unsupported format fail clearly without replacing the working form?
• What happens after a concurrent publish, interrupted migration or retried migration?
• After rollback, can old and new records still be read, and are any writes incompatible?