Working with Version in Salesforce is mostly inventory and audit work rather than active configuration. The platform manages version assignments for new components; the operational task for an admin or developer is auditing existing components for stale versions, planning upgrades when Salesforce deprecates a behavior, and confirming version compatibility before deploying or installing. This guide covers the common audit and bump workflow that most teams run on a quarterly cadence.
- Inventory API Version across your custom code
Run SOQL queries against the ApexClass, ApexTrigger, ApexPage, AuraDefinition, and LightningComponentBundle metadata objects, selecting ApiVersion and grouping by version number. The result is a histogram of how many components are pinned to each version. Anything more than ten releases behind the current platform version is a candidate for an upgrade audit. Export the result to a spreadsheet and tag each row with the responsible team or product line. This list is the input to the next quarter upgrade work.
- Read the version-by-version compatibility guide
For each version gap you plan to close, open the Salesforce developer documentation and read the version-by-version compatibility guide for that range. Salesforce documents every behavioral change between releases. Identify which changes apply to your code (DML behavior, governor limits, exception types, namespace rules) and flag the components most likely to be affected. The guide is the single best source of truth for what to test during a version bump. Skipping it and hoping the tests catch everything is the most common reason version upgrades break in production.
- Bump versions in a sandbox with full test coverage
Open each component flagged for upgrade, bump the API version one release at a time, and run the full Apex test suite after each bump. Do not jump ten versions in one move. The version-by-version approach catches issues at the step where they are introduced rather than at the end where the root cause is buried. Document any code changes the bump requires in the team release tracker so the same code does not break next time. Sandbox-test the change for at least one full release cycle before promoting to production.
- Audit Package Versions for installed managed packages
Open Setup, Installed Packages, and review the version of every managed package in the org. Compare against the latest version each Publisher offers on AppExchange. Identify packages two or more major versions behind, since those are the most likely to have unresolved security fixes or behavioral updates. Coordinate with the Publisher to confirm the upgrade path is supported and contains no breaking schema changes. Schedule the upgrade in a sandbox first, then promote to production with a documented rollback plan.
- API Version is set per component, not per org. Different Apex classes in the same org can run on different versions, and the same code can behave differently across versions. Audit before assuming consistency.
- Managed package major version bumps may include schema changes. Read the Publisher release notes carefully and test in sandbox; do not assume a major version upgrade is drop-in for any non-trivial package.
- Sandboxes run one release ahead of production during the preview window. Code that works in sandbox during preview may behave differently in production until production upgrades to the same release.
- Deprecated behavior is removed without notice if you ignore the deprecation announcement. Salesforce publishes the removal target in release notes; read them every release or risk surprise breakage.
- Flow versions do not show up in standard reports without a custom report type. Build the report type once, then add it to your governance dashboard so old flow versions do not accumulate unnoticed.