A Shape change renamed or removed something

​

Signs

• penumbra shapes diff <draft-id> lists a change marked (losing) or (breaking), or a recommended bump of major.
• penumbra shapes diff <draft-id> lists a rename. It marks the rename (preserving), yet older entities do not follow it.
• After the publish, penumbra graph update <entity-id> is refused with graph_plan_rejected when you give the entity a property that only the new version has. The message names no property, and its next: line does not point here.
• penumbra graph workspace validate on a workspace that holds an older entity prints missing_property_declaration for a property that only the new version has.
• penumbra context explore --shape-id <shape-id> --json shows entities whose shape.artifact_digest is not the newest in penumbra shapes log <shape> --json.

​

Why it happens

A publish adds a version to the Shape. It rewrites no entity. Each entity keeps the version that it was saved under, with the names that it was saved with. A newer version takes over an older entity only when the change between the two keeps its meaning and renames nothing. A breaking change fails that test. The entities stay readable and visible, and you can still edit them with the properties of their own version. They cannot take what the new version added or renamed. Penumbra does not migrate them.

​

What Penumbra does

By itself:

• Keeps every entity on the version it was saved under. A publish changes no entity.
• Keeps every published version readable.
• Lets an edit that uses only the properties of the entity’s own version succeed, and keeps the entity on that version.
• Refuses an edit that gives the entity a property that only the new version has, with graph_plan_rejected.
• Reads a Shape at the version a workspace pinned. A new workspace reads the newest version.

You must:

• Read penumbra shapes diff before you publish, and tell the person which changes are breaking and which entities they leave behind.
• Count the entities that the change touches.
• Offer the person a choice, and wait for the answer.

Not handled:

• No operation moves an entity to a newer version after a breaking change.
• No warning at publish time says how many entities stay behind.
• penumbra shapes diff marks a rename as preserving, though entities do not follow it.

​

Do

1. Stop before the publish. Read the diff: penumbra shapes diff <draft-id>. Note each change marked losing or breaking, each rename and the recommended bump.
2. Count the entities of each changed type: penumbra graph counts. List them with penumbra context explore --shape-id <shape-id> --limit 200 --json. Add --cursor <cursor> for the next page.
3. Tell the person what the change does, in words they use. Offer these choices.
   • Make the change additive. Keep the old property and add a new optional one. Widen an enum instead of narrowing it. Keep a required property optional. Older entities then follow.
   • Publish the breaking change. Older entities stay on their version. New extractions and new entities use the new version.
   • Publish the breaking change, then replace the entities that matter. This creates new entities at the new version and deletes the old ones (step 6).
4. After the person chooses, edit the draft file and push it again (card shape-draft). Check and diff again.
5. Publish: penumbra shapes publish <draft-id> -m "<what changes>". If the project’s policy holds shape_change, a key or a connected agent waits for approval (problem change-waits-for-approval).
6. If the person chose replacement, extract again from the Files (recipe extract-files). Compare the proposals with the old entities (recipe find-stale-entities). Delete an old entity only after the person agrees. The delete removes its relationships too, and a key waits for approval (card rules entity.3 and entity.4).
7. Edit an entity that stays on the old version with the properties of that version. Run penumbra graph update <entity-id> --revision <n> --properties '<every property>'. The edit replaces the whole property map (card rule entity.2).

​

Don’t

• Don’t report the change as done after the publish. The entities that exist still hold the old shape.
• Don’t rename by changing a ref. A new ref is a new property, and the old one counts as removed. Change only the name and keep the ref.
• Don’t delete entities to move them to the new version before the person agrees. A delete takes their relationships with it (card rule entity.3).
• Don’t try to give an older entity a new property through a workspace. The workspace plans the change under the version of the entity, and refuses the property with missing_property_declaration.

​

Check

• The person has chosen one of the choices in step 3, in the chat.
• penumbra shapes log <shape> shows the new version with your message.
• Every entity listed in step 2 is on the newest version, or you have told the person which ones stay on an older version. Compare artifact_digest under shape in the explore output with penumbra shapes log <shape> --json.

​

Related

Card rules shape.3, shape.4, shape.5 and shape.6. Card shape-draft. Recipes change-a-shape and extract-files. Problems view-needs-republish and change-waits-for-approval.

​

Keep going

Shape · Shape draft · Change a Shape and publish it · Entity · Workspace · A View does not follow a Shape change until it is published again