Destructive changes

Deleting a component from a package removes it from your source — not from the orgs the package was already installed in. An org deletes metadata only when a destructive change ships to it. How a destructive change is expressed depends on the package's type.

Unlocked packages

The platform handles deletion as part of the version upgrade: metadata present in the installed version but missing from the new one is removed when the new version installs. codev installs unlocked packages in mixed mode, so components the platform can delete are deleted; components the platform only deprecates — such as custom fields holding user data, or components still referenced elsewhere — remain in the org for manual removal. Engine reference: Destructive changes.

Source and diff packages

A source package (and its diff variant) expresses deletions through two folders inside the package directory: components in pre-destructive/ are deleted before the package's contents deploy, components in post-destructive/ after.

src/feature-management/
├── main/
│   └── default/          # the package's components
├── pre-destructive/      # deleted before the deployment
└── post-destructive/     # deleted after the deployment

The installation is a single deployment transaction — the refactored components and the deletions apply together. That matters because Salesforce refuses to delete a component that something else still references: the same transaction can remove the references and the component.

Once the version carrying a destructive change has installed on every environment, remove the destructive folders in a follow-up change. There is no urgency — installs ignore warnings about components already absent from an org.

Data packages

A data package deletes records, not metadata, through the operations its export.json declares — a delete operation scoped by a query, or deleteOldData to remove records that no longer exist in the package before loading the rest. Engine reference: Destructive changes — data packages.

A destructive change is a change

Deletions travel the same lifecycle as any other change: they arrive on a pull request, validation deploys them to a review environment — the deletion is tested against a real org before the merge — the merge builds them into the artifact, and each release applies them to its environment.

Tracking components left behind

A component removed from a package without a destructive change stays in the orgs it was deployed to. codev's Component Cleanup records every component dropped from a package, per branch, with a status — pending cleanup, moved to another package, handled by a destructive change, restored, or dismissed — and verifies against each registered environment whether the component is actually still present. It tracks and verifies; the removal itself is a destructive change you ship through the package. See Component Cleanup.