> ## Documentation Index > Fetch the complete documentation index at: https://docs.pnbr.io/llms.txt > Use this file to discover all available pages before exploring further. # A Shape change renamed or removed something > After a breaking Shape change, entities that exist stay on their old version, and Penumbra has no operation that moves them to the new one. Troubleshooting · shapes > **Use when** > > A draft changes a Shape by renaming, removing or tightening a type, a property or a relationship, or a published change did so. > **Looking for something else?** > > An additive change, which older entities follow (recipe [Change a Shape and publish it](https://docs.pnbr.io/guides/change-a-shape.md)). A View that refuses after a publish (problem [A View does not follow a Shape change until it is published again](https://docs.pnbr.io/troubleshooting/view-needs-republish.md)). ## Signs * `penumbra shapes diff ` lists a change marked `(losing)` or `(breaking)`, or a recommended bump of `major`. * `penumbra shapes diff ` lists a rename. It marks the rename `(preserving)`, yet older entities do not follow it. * After the publish, `penumbra graph update ` 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 --json` shows entities whose `shape.artifact_digest` is not the newest in `penumbra shapes log --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 `. 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 --limit 200 --json`. Add `--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](https://docs.pnbr.io/concepts/shape-draft.md)). Check and diff again. 5. Publish: `penumbra shapes publish -m ""`. If the project's policy holds `shape_change`, a key or a connected agent waits for approval (problem [change-waits-for-approval](https://docs.pnbr.io/troubleshooting/change-waits-for-approval.md)). 6. If the person chose replacement, extract again from the Files (recipe [extract-files](https://docs.pnbr.io/guides/extract-files.md)). Compare the proposals with the old entities (recipe [find-stale-entities](https://docs.pnbr.io/guides/find-stale-entities.md)). 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](https://docs.pnbr.io/concepts/entity.md#rule-entity-3) and [entity.4](https://docs.pnbr.io/concepts/entity.md#rule-entity-4)). 7. Edit an entity that stays on the old version with the properties of that version. Run `penumbra graph update --revision --properties ''`. The edit replaces the whole property map (card rule [entity.2](https://docs.pnbr.io/concepts/entity.md#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](https://docs.pnbr.io/concepts/entity.md#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 ` 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](https://docs.pnbr.io/concepts/shape.md) in the explore output with `penumbra shapes log --json`. ## Related Card rules [shape.3](https://docs.pnbr.io/concepts/shape.md#rule-shape-3), [shape.4](https://docs.pnbr.io/concepts/shape.md#rule-shape-4), [shape.5](https://docs.pnbr.io/concepts/shape.md#rule-shape-5) and [shape.6](https://docs.pnbr.io/concepts/shape.md#rule-shape-6). Card [shape-draft](https://docs.pnbr.io/concepts/shape-draft.md). Recipes [change-a-shape](https://docs.pnbr.io/guides/change-a-shape.md) and [extract-files](https://docs.pnbr.io/guides/extract-files.md). Problems [view-needs-republish](https://docs.pnbr.io/troubleshooting/view-needs-republish.md) and [change-waits-for-approval](https://docs.pnbr.io/troubleshooting/change-waits-for-approval.md). ## Keep going [Shape](https://docs.pnbr.io/concepts/shape.md) · [Shape draft](https://docs.pnbr.io/concepts/shape-draft.md) · [Change a Shape and publish it](https://docs.pnbr.io/guides/change-a-shape.md) · [Entity](https://docs.pnbr.io/concepts/entity.md) · [Workspace](https://docs.pnbr.io/concepts/workspace.md) · [A View does not follow a Shape change until it is published again](https://docs.pnbr.io/troubleshooting/view-needs-republish.md) Penumbra Grammar 0.6.26 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.