Upgrade an existing case

A new release of affirmatrix can add a field to the records it writes. The case keeps its own copy of the schemas, and that copy refuses every field it does not know. So a case that an older release wrote needs a schema refresh before its first sync with the new release.

This page uses one such field as its example: seg:extractedFrom, the extraction revision on each node record (0016. A node record carries the revision its content hashes were extracted at). The steps are the same for every schema change.

Run every command from the directory that holds affirmatrix.yaml. The examples name the case case/.

Before you start

• Commit every change in the case. The steps below give one commit each, and an earlier change mixed into them is hard to review.

• Map each content repository under repositories: in the configuration. The tool records a revision only for a repository the configuration maps.

• Commit the content in each content repository. A node whose anchored path has a change that is not committed, or that no commit holds, gets no revision.

The sync is refused until the refresh

A case with the old schema copy refuses the sync. The sync exits 2 and writes nothing:

$ affirmatrix case sync
node '<id>' does not validate against requirement.schema.json: Additional properties are not allowed ('seg:extractedFrom' was unexpected)
$ echo $?
2

<id> is the first node record the sync tried to write. The case does not change, so you can run the steps below at any time.

1. Refresh the schema copy

$ affirmatrix case refresh
refreshed: implementation.schema.json
refreshed: requirement.schema.json
refreshed: test_outcome.schema.json
refreshed: test_specification.schema.json
refreshed: waiver.schema.json

The command names each schema that differed. A case that is older still can show more lines. If the copy is already current, it prints schema copy up to date. Both outcomes exit 0.

2. Review the schema diff

$ git -C case diff --stat
$ git -C case diff

For this release, each node schema gains one optional property, seg:extractedFrom. Look for any other change you did not expect before you go on. A refresh can also rewrite records of an older case (0012. Evidence edges have their own link states gives one example), and the diff shows those too.

3. Commit the refresh

The commit is a store act. You make it; the tool runs no git.

$ git -C case add -A
$ git -C case commit -m "<your message>"

4. Sync

$ affirmatrix case sync
synced case
$ echo $?
0

If the sync cannot record a revision for some node records, it prints one line for each repository, with the number of node records:

no extraction revision: <repository>: <count> node records

The usual causes are in “Before you start”: a repository the configuration does not map, or an anchored path with a change that is not committed. Fix the cause and sync again.

5. Review and commit the sync

The first sync gives one large diff. It adds seg:extractedFrom to every node record whose anchored paths were clean. If no content changed since the last sync, that field is the only change. No hash changes, because the field never enters a hash:

$ git -C case diff --stat
$ git -C case diff

Each node record gains a block of this form:

"seg:extractedFrom": {
  "<repository>": "<revision>"
},

Commit it, again as a store act:

$ git -C case add -A
$ git -C case commit -m "<your message>"

A second sync with no content change writes nothing new. A recorded revision changes only when the node’s hashes change.