Because projects in DevOps Center require a source control repository that uses the Salesforce DX project structure, each DevOps Center project contains a configuration file, sfdx-project.json. During each Salesforce release cycle, make a plan to update the source API version to avoid metadata type version mismatch errors when moving changes through your release pipeline.
When you create a new project source control repository, each pipeline and feature branch created from the main branch contains its own version of the DX project configuration file. However, this file isn’t updated automatically during Salesforce release transitions. In most cases, the only value that requires updating is the sourceApiVersion option.
The sourceApiVersion option in sfdx-project.json determines the version of metadata that is retrieved when you commit changes to a work item feature branch, or when you promote changes through the release pipeline. This value is important if you’re using a metadata type that has changed in a recent release or if you want access to new metadata types during or after a release transition.
For example, let's say a new field was added to the CustomTab object for API version 63.0. If the sourceApiVersion in your sfdx-project.json file is version 62.0, you see errors when promoting changes that include the new field.
If you’re working in an existing DevOps Center project for a while, it’s likely that the sourceApiVersion is outdated.
Update During Development When Working on a New Work Item
If you're actively working on changes, this method is the easiest for updating the source API version in your pipeline.
If the source API version isn’t updated, some unexpected behaviors occur:
- When you try to add components manually to a work item, you don’t see them in the Add Components list.
- You receive errors when you try to commit changes to the work item feature branch.
- You receive any metadata version mismatch errors when trying to promote changes to the first pipeline stage.
An easy way to resolve the issues is to update the sourceApiVersion in the sfdx-project.json file in the work item’s feature branch. The work item must also contain metadata changes as well as the changes to the DX project file.
As you promote this work item through the release pipeline and eventually release it to production, the DX project file is updated in each pipeline stage’s branch and the main branch.
Manually Update in Each Pipeline Branch and Any Required Feature Branches
To prepare for the next Salesforce release, or during the planning phase for your next project, you can proactively update the DX project files in every branch so team members don't run into issues when developing and testing new changes.
Manually update the sourceApiVersion in every branch’s DX project file directly in the source control repository. To ensure successful promotions, update the main branch, each pipeline stage branch, and any feature branches.