Working effectively with Salesforce metadata combines knowing the metadata types involved in your changes, using the right tools for deploy and retrieve, and following source-control discipline. The workflow below covers the standard sequence for a metadata-based development project.
- Set up a Salesforce DX project
Install the Salesforce CLI and the Salesforce Extensions for VS Code. Initialize a new SFDX project (sf project generate). Set up the project structure with packageDirectories for each logical grouping of metadata. Authorize the relevant orgs (Dev Hub, sandboxes, production). Configure source tracking on the development sandbox if available. Commit the initial project structure to source control before any changes.
- Retrieve existing metadata into source
For changes to existing metadata, retrieve the current state from the org into your local project (sf project retrieve start). Choose between retrieving everything (broad but slow) or specific metadata types and members (targeted but requires knowing what to retrieve). Inspect the retrieved files in source format. Commit the baseline before making any edits, so the diff between baseline and your changes is clear.
- Make and test changes locally
Edit the metadata files locally. For each change, document what is changing and why. Run any local validation. Push the changes to a scratch org or dev sandbox (sf project deploy start). Test the changes against representative data. Iterate until the changes work as expected. Commit each logical change as a separate commit so the source history tells the story of what was done.
- Deploy through the pipeline to production
After local testing, deploy through the standard pipeline. For SFDX-based pipelines, push the source branch and let CI/CD build and validate. For Change Set-based pipelines, package the changes and promote. For DevOps Center, follow the work-item promotion flow. At each stage, run tests and validate the metadata deploys cleanly. Resolve any conflicts or dependencies. Document the production deployment in the team's release log.
- Source format and metadata format are not interchangeable in a single project. Pick one and stick with it.
- Profile and PermissionSet deploys often fail because of references to removed components. Audit before deploying.
- Wildcard package.xml entries do not work for all metadata types. Some require explicit member lists.
- Custom Metadata Types (the feature) are not the same as metadata types (the platform concept). Be precise about which you mean.
- Some metadata types are not deployable through change sets. Check the Metadata Coverage Report.