Understanding metadata types is one thing; using them well in a release pipeline is another. The workflow below covers the standard sequence for retrieving, modifying, and deploying metadata in an SFDX-based project, which is the modern way to work with the Metadata API.
- Identify the metadata types affected by your change
For each business change, list the metadata types involved. A new field involves CustomField, possibly Profile or PermissionSet, possibly Layout, possibly ValidationRule. A new Lightning page involves FlexiPage. A new Flow involves Flow and possibly Permission or Object dependencies. Make this list before writing code so you know what will travel through the pipeline. Surprises during deploy almost always trace back to a metadata type that was overlooked at this step.
- Retrieve from sandbox into your local source
Use sfdx force:source:retrieve --metadata Type:Name to pull the specific component into your local project, or use the source tracking commands to pull every change since your last sync. Inspect the resulting files in source format. Each metadata type becomes one or more XML files under its parent folder. Commit the retrieval before making your edits, so the diff between original and modified state is clean for code review.
- Make and commit your changes
Edit the XML or component files locally. Add new fields by adding new files (in source format) or new sub-elements (in metadata format). Update existing components by modifying the right files. Run any local validation (sfdx force:source:validate or build pipeline checks). Commit each logical change as a separate commit so the history tells the story of what changed and why. Push to your branch and open a pull request for review.
- Deploy to the target org with a validated package.xml
After approval, run sfdx force:source:deploy or use DevOps Center to push the changes to the target org. The deploy goes through dependency resolution, running tests for any Apex changes (75% coverage required for production), and reporting any conflicts. Read the deploy output carefully; metadata-type-specific errors usually point exactly at what is missing or misconfigured. Successful deploys move you to the next environment in the pipeline; failures send you back to fix the issue.
- Wildcard package.xml entries do not work for all metadata types. Profile and PermissionSet need explicit member lists in many cases.
- Source format and metadata format are not interchangeable inside a single project. Pick one and stick with it. SFDX projects use source format by default.
- Dependency order matters across deploys. A profile referencing a removed object fails to deploy. Remove the dependency first, then redeploy the profile.
- CustomLabel removals require manual editing in the target org or destructiveChanges.xml; the standard deploy treats CustomLabel as append-only.
- Some metadata types do not deploy through change sets at all. Check the metadata coverage report before assuming a type is change-set-deployable.