Deprecating Components with Salesforce CLI
 

Salesforce CLI supports a structured and safe approach to metadata cleanup using pre- and post-destructive change manifests. This allows teams to:

• Pre-Destructive Changes: Remove outdated components before deploying new metadata, preventing conflicts or dependency issues.
• Post-Destructive Changes: Clean up legacy components after deployment, ensuring a leaner, more maintainable org.

By integrating these manifests into your deployment workflow, you can safely deprecate obsolete metadata while maintaining org integrity and deployment consistency.

Create a Destructive Changes Manifest

1. A destructiveChanges.xml file defines metadata components you want to delete from your Salesforce org. It’s used in deployment workflows to clean up obsolete elements either before or after deploying new metadata.
   Sample destructivechanges.xml:

   
   <?xml version="1.0" encoding="UTF-8"?>
   <Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
      <members>MyOldComponent</members>
      <name>ApexClass</name>
    </types>
    <version>63.0</version>
   </Package>

   Use Specific Names: List exact component names to avoid accidental deletions.
   Group by Type: Organize deletions by metadata type (e.g., ApexClass, CustomObject, Workflow)

2. Creating a Minimal package.xml for Destructive Changes
   Even though you're only deleting components, Salesforce mandates the presence of a package.xml file in the deployment directory. This file can be completely empty except for the version declaration.
   Minimal example:

   <?xml version="1.0" encoding="UTF-8"?>
   <Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <version>63.0</version>
   </Package>

       Why It's Required

• Deployment Structure: Salesforce expects a complete metadata package structure, even if you're only removing components.
• Version Control: The <version> tag ensures compatibility with the Metadata API version you're targeting.
• Validation: Helps the CLI validate the deployment context, even if no new components are being added.
   

Deploy Using Salesforce CLI

Deprecated components were successfully validated and removed using Salesforce CLI, leveraging both pre- and post-destructive change manifests. This structured approach ensured:

• Safe deletion of obsolete metadata before and after deployment
• Seamless integration with new components defined in package.xml.
• Clean and conflict-free deployments, reducing technical debt and improving org maintainability.
   

Pre-Destructive changes 

Deletes components before deploying new metadata..
Purpose: Removes components listed in destructiveChangesPre.xml before deploying new metadata. This ensures that outdated, conflicting, or deprecated components do not interfere with the deployment process.

Use case:

• Removing legacy components that conflict with new versions.
• Clearing out obsolete metadata that is no longer referenced.
• Preventing deployment errors due to naming collisions or dependency issues.
  
  How it Works: The Salesforce CLI processes the destructiveChangesPre.xml file first, deleting specified components before applying the new metadata defined in package.xml

sf project deploy start --manifest manifest/package.xml --pre-destructive-changes manifest/destructiveChangesPre.xml --target-org aliasName

• --manifest: Points to your package.xml file containing the metadata components you want to deploy.
• --pre-destructive-changes: Specifies the destructiveChangesPre.xml file to delete components before deployment.
• --target-org: Indicates the alias of the org you're deploying to (e.g., --target-org MySandbox).
  
  Ensure your XML files are properly formatted and that your org alias is authorized (the 'sf org list' command can help confirm this).

Post-Destructive changes

Purpose: Deletes components listed in destructiveChangesPost.xml after the deployment completes.
Use case: Clean up legacy components that are no longer needed once the new metadata is in place.

sf project deploy start --manifest manifest/package.xml --post-destructive-changes manifest/destructiveChangesPost.xml --target-org aliasName

      What Each Flag Does:

• --manifest: Points to your package.xml for components you want to deploy.
• --post-destructive-changes: Points to your destructiveChangesPost.xml for components you want to delete after deployment.
• --target-org: Specifies the org alias you're deploying to.
  
  Confirm No Dependencies: newly deployed metadata does not reference the components marked for deletion.
   

Validate Deployment (No changes made)

Purpose: Running a deployment validation with pre- and post-destructive change manifests helps ensure that deprecated metadata can be safely removed either before or after deploying new components without compromising org integrity.

Why Validate?

• Safety First: Confirms that deletions won’t break dependencies or cause runtime errors.
• No Changes Made: Validation simulates the deployment without modifying the org.
• Early Detection: Identifies issues before they reach production.
   

Pre-Destructive Validation

sf project deploy validate --manifest manifest/package.xml --pre-destructive-changes manifest/destructiveChangesPre.xml --target-org aliasName

Post-Destructive Validation

sf project deploy validate --manifest manifest/package.xml --post-destructive-changes manifest/destructiveChangesPost.xml --target-org aliasName

Best Practice

• Use the "sf org" list to confirm your alias is correct.
• Run in a sandbox or scratch org before deploying to production.
• You can also use --dry-run to simulate the deployment without making changes.
• Track changes in Source Control to recover deleted components.

• Clean up unused metadata regularly to keep your org lean.