Upgrade a document when WCL moves

§ 1Purpose

Bring a WCL model back in sync after installing a newer wcl release.

§ 2Prerequisites

A model with source blocks recording reflects_version, and a newly-installed wcl binary.

§ 3Flowchart

§ 4Steps

§ 4.11

§ 4.2Compare recorded and installed versions

console

$ wcl --version
wcl 0.25.0-alpha
$ grep reflects_version wskill.wcl
  reflects_version = "0.24.1-alpha"

Read each source's reflects_version and compare it against the installed wcl --version. If they already match, stop — there is nothing to upgrade. Otherwise every source that lags marks content to re-verify.

§ 4.32

§ 4.4Re-run wcl check on the model

console

$ wcl check wskill.wcl

Exit codes

0 = valid, 1 = parse error, 2 = schema violation — a new release can tighten either.

Run wcl check on the model's root document with the new binary. A release can add constraints, change builtin behaviour, or deprecate syntax, so a file that was clean under the old version may now report errors.

§ 4.53

§ 4.6Fix what the new version rejects

console

$ wcl check wskill.wcl
ok            # after fixes

Work through the reported errors — each names the file, span, and rule. Fix the source (not the schema, unless the release genuinely changed the vocabulary) and re-run wcl check until it is clean.

§ 4.74

§ 4.8Re-render the projections

console

$ just render

Rebuild every shipped view so the generated output reflects the upgraded model. Spot-check a page or two — rendering can change even where validation stayed green.

§ 4.95

§ 4.10Bump the version metadata

console

$ wcl set wskill.wcl topics.wcl.version '"0.25.0-alpha"'

Record the upgrade: bump topic.version, and update each touched source's last_checked date and reflects_version to the new release. The next upgrade sweep starts from these fields.

Verification

wcl check is clean under the new binary, the projections rebuild, and every source's reflects_version matches wcl --version.