Back at the start of the year, we wrote a post about Gearset intelligently handling API versioning so that you don’t have to. We explained that Gearset will automatically pick the highest commonly-supported version between source and target and use that by default, while still allowing you to specify an overriding version, should you need to.
As for version control repositories, Gearset treated these as containing version 37 metadata unless you applied the version override. This worked well enough, but came with the additional burden of having to pick an API version to use for each comparison when comparing to a source control repository containing anything other than version 37 metadata. In a recent change, we’ve made Gearset smarter when comparing to version control and uploaded metadata zips.
Metadata API versions and version control
When using version control, your repository will contain metadata extracted via a specific version of the API. As new versions of the API are released, you have two options: stick with the current API version when working with your repository, or switch to using the new API version and “upgrade” the metadata in your repository.
There are a variety of factors that might affect this decision, for example whether there are new features that you’re taking advantage of that are only supported via the newer API version, bugs in Salesforce’s downgrading of metadata to older API versions, or a commendable desire to remain up to date with API version updates. Version updates arrive with a regular cadence, so it’s important to plan not only for managing the metadata upgrades, but also deferring them until the time is right for your project.
How Gearset helps
Gearset helps in two ways:
- Gearset already chooses the highest commonly-supported API version for the source and target of your comparisons, meaning you’ll never accidentally get version mismatches
- With our recent update, Gearset will attempt to detect the API version associated with the metadata in your source control repository, instead of assuming V37
The highest common version approach to selecting API versions is already covered in our previous post, but how does the API version detection work for source control repositories?
Detecting a source control repository’s API version
When selecting a git repository or uploading a zip or folder of metadata as the source or target of a comparison, you’ll notice the app display the detected API version:
Behind the scenes, Gearset is taking the contents of that repository and running checks to determine the version of the metadata within. At the time of writing, the checks are fairly limited — if a package.xml is present, Gearset will assume the repository contains metadata based on the API version specified therein. If we don’t detect a package.xml, Gearset will fall back to the default which is still currently version 37.
This doesn’t only apply to comparisons — Gearset will use the same detection mechanism whether for comparisons, clones, rollbacks, CI jobs, monitoring jobs, and so on. As before, if you specify an API version override, Gearset will respect the override above the detected version giving you the same control over API versions as before.
Upgrading your repository’s metadata
This detection makes it very easy to manage API version upgrades. If you specify an API version in a package.xml in your repository, Gearset will pin to that version until you update it to specify the newer version. Once the version number is updated, running a comparison from the associated org to that repository will highlight all the differences caused by the version upgrade, and give you the opportunity to review those changes and commit them back to your repository. That’s all there is to it!
Conclusion
As we mentioned in our last post, metadata version bumps can catch you off guard. Gearset hides all of the complexity of API version matching for all operations, whilst giving you full control over when to run upgrades to newer API versions.
If you have any feedback on how Gearset handles API versioning, or any other aspect of Gearset, then let us know at [email protected], or through the live chat!