SFDX Source Deployment Vs Metadata API Deployment

What is the difference between metadata api deployment and source deployment in Salesforce?

If you search in google, we can find a couple of contents which are copy-pasted from Salesforce documentation or from other blogs. Everyone says about two basic differences: 

1. Project folder structure is different 

2. In place of a single large metadata file, source format has individual metadata files for subcomponents of a parent component (eg. Custom object)

But, Salesforce did not introduce the source structure for metadata of subcomponents of all parent components yet. For example, workflow rule and sharing rule. Workflow rule has subcomponents like alert, field update, email message etc. Also, sharing rule has subcomponents like sharing criteria rule and sharing owner rule. But, unfortunately, there is no individual metadata file for those subcomponents of sharing rule and workflow rule in source format. Instead, both sharing rule ad workflow rule have a single metadata file which contains the tags for their subcomponents,

We can hope that Salesforce will soon introduce individual metadata file for subcomponents of sharing rule and workflow rule. Ok. let us come to the point.

What I have mentioned above are not the real difference between metadata api deployment and source deployment. What we need to know is the real difference between the impacts made by metadata api deployment and source deployment. Unfortunately, I couldn't find any helpful documentation regarding that.

Let me present my findings. I don't claim that everything I am going to tell is right. The reason is that no one will get the opportunity to perform every use cases of deployment. So, please feel free to correct me. Then it will be very good learning resource for others also.

Metadata API Deployment

Metadata api deployment always look for a specified list of metadata to be deployed and that is called manifest file or package.xml. You can bundle together all of your metadata files in metadata api format in a specified folder or zip folder along with a package.xml referencing all the components in the folder. Metadata deployment will replace only the components specified in the package.xml. Let me give an example of sharing rule deployment.

Suppose that you have changed an exiting sharing criteria rule of Case. The change happens in metadata of Case sharing rule and you pushed Case sharing rule metadata to a folder. You have created a package.xml with Sharing Criteria Rule component of Case. Metadata api deploy command will look into package.xml and it will pick only the metadata of changed sharing criteria rule from the Case sharing rule metadata in the folder and replace the same sharing criteria rule in target org. No other parts of Case sharing rules will not be touched.

Suppose that you have accidentally created package.xml with Sharing Rule in place of Sharing criteria rule. This can happen when you create package.xml using VS Code package xml builder. In this case, metadata api command will deploy the entire Case sharing rule metadata to target org.

Source Deployment

For source deployment, manifest file is not necessary. Source deploy command can directly deploy the metadata of components from a specified folder too. So, it will replace the metadata of the component in the target org fully with metadata in the folder.

You must be very careful when you will deploy metadata from a folder using source deploy command. Suppose that you have pulled only your Case sharing criteria rule to local project folder. So, case sharing rule metadata will have only your sharing criteria rule metadata tags. Then, you accidentally pushed that stripped Case sharing rule metadata to deployment folder. Source deploy command will replace the Case sharing rule metadata in target org with what you have pushed and as a result all except your sharing criteria rule will be wiped out from Case sharing rule of target org.

The possibility of this danger can be avoided by using manifest file. Source deployment can be done with help of manifest file also. But, in source deployment manifest will always reference the components in default project folder. In this scenario, metadata deployment is same as source deployment with manifest file, but with out any specific deployment folder.

Destructive Deployment

The main difference between metadata api deployment and source deployment lies in destructive deployment. In metadata api deployment, we can do constructive and destructive deployment together in single metadata api deploy command. But, that is not possible for source deployment. Normal source deploy command will perform constructive deployment only. You need to call source deploy command again for destructive deployment. But destructive source deployment has another advantage. You can decide if the components will be deleted before or after constructive deployment with two different types of destructive package.xml

Recommended Deployment Strategy 

If your project has metadata api structure, you can use metadata api deploy command. If your project has source folder structure, you can use source deploy command. But in case of source structure, if you have some components to delete and you would like to do it along with constructive deployment, you should convert source structure to metadata api structure and metadata api deploy command must be used.