How to manage API version differences in packages and subscribers?

Question

I think we can all agree that in an ideal world whenever we upgrade the SF API in managed package code we desire stability in subscriber orgs.

Unfortunately this appears far reaching in the world of Salesforce. Assume the following:

Package PKGA

• UtilityClass - on API v27.0 (written few years ago)

Package PKGB

• ServiceClass - on API v20.0 (written many years ago)
• Uses PKGA

Clients

• Use both packages
• All local code is automatically on the latest API (e.g. 37.0)

With this setup certain functions in PKGA may not work in older subscribers (PKGB) or newer ones (clients). This problem is demonstrated in this SFSE post. To fix this we would need to make the API version across all orgs equal. But, all new code written in client orgs will always be on the latest API! This means if I update the API version in both packages to 37.0 the client will be on 38.0 by next quarter.

This gets even more complicated when there is existing code in the client orgs. Because how often do you update the API version of code written 6 months ago in a LIVE org? Probably never. Even if we keep our packages up to date with the most recent API version the clients can now fall behind!

This looks like a vicious cycle with no viable solutions. The goal here is to achieve stability and confidence in our package upgrades. I appreciate any and all ideas.

Answer 1

As an ISV, you should be updating your packages to the latest API version every few releases. There's simply no exception to this; failure to do so accumulates technical debt in terms of maintenance you'll have to do later. It's like driving your car without proper maintenance. Yes, you can go longer than the recommend manufacturer intervals, but you risk things breaking sooner.

How I'd recommend doing it is as follows: release your package once a release, three times a year. Update all of the code to the latest API version, do regression testing, then update the package. Keep track of which upload corresponds to which API version. If your clients are stuck on version 27.0, give them a 27.0 package. When they decide to update their code to version 28.0, give them the upgraded API version package as well.

If you do this every release, you'll reduce your own technical debt, and if your clients want to use the new features you release, they'll be forced to clear their own technical debt. If they don't want to upgrade their code, they can remain on the older package. If you have the spare resources, you can offer extended support for older releases or to help clients upgrade.

For now, I'd suggest you start upgrading one version at a time. Move the version 20.0 code to 21.0, do regression testing, then upload the new version. Lather, rinse, repeat. Give your clients a notice when each new upgrade comes out. Let your clients decide if they want to update. There's no rule that says a client must be on the latest version of a package. You can keep your old version 20.0 code as the default installed package, but let users know they can upgrade to a later version by contacting support.