Supporting package upgradability

Having just created and released your package, you can start to share it with your customers. Later in this chapter, we will discuss ways to list your package and install it. Before we get too far ahead though, let’s first consider a very important aspect of managing your package – upgradability. As customers embrace your application, they will customize its features and APIs and expect them to continue working even after upgrades to the latest version.

Upgrading a package is as simple as installing the new version over an existing version (we will do this in the next chapter). The Salesforce Platform manages package upgrades for you, without asking users to log out of the system or experience any interruption.

Salesforce second-generation managed and unlocked packages have built-in support for upgradability and also help remove a lot of the traditional pain of ensuring you do not accidentally make breaking changes to your application or even, in most cases, worrying about writing upgrade scripts. For example, it will prevent you from deleting a Custom Object or field that has previously been included in a released package or modifying an Apex global class or method.

Managing package ancestry

Managing ancestry lineage is a feature of second-generation managed packages, if you are not an ISV developer or are using the unlocked package type you can skip to the Installing and testing your package section later in this chapter to understand more about installing your package for testing.

A package version ancestry is the lineage a valid upgrade path takes; in a simple case, this might be v1.0 to v1.1 to v1.2, and so on. In this case, the ancestor of v1.2 is v1.1 and the ancestor of v1.1 is v1.0, meaning that customers can upgrade from v1.0 to v1.1 or even from v1.0 straight to v1.2. We will follow this simple serial ancestry lineage as we build out the package throughout this book. That way, you will see the value of package upgradability. In a more complex scenario, you may decide to split your upgrade paths if you decide to take a radically different direction with the product for new customers. In which case, you might start a new upgrade path like so: v1.1 | v1.2 | v2.0. This obviously needs very careful consideration but does allow you more freedom should you need it.

The ancestorId or ancestorVersion configurations within the sfdx-project.json file define the ancestry for the package version you are currently developing in your scratch orgs. We will explore what effect this has on developing in a scratch org later. This configuration also denotes the desired upgrade path during package creation, as described previously.

You can only define an ancestor of your next version based on an already released version of your package. In this chapter, we will use ancestorVersion with the value of HIGHEST, which is recommended by Salesforce as the simplest approach to following a linear package release path. If you want to base your next package version on a different ancestor, you must use an explicit alias name or ID.

Add the ancestorVersion configuration to the sfdx-package.json file as shown here:

{
 "packageDirectories": [
   {
     "path": "source/formulaforce",
     "package": "FormulaForce App",
     "versionName": "ver 1.1",
     "versionNumber": "1.1.0.NEXT"
     "versionDescription": "FormulaForce App",
     "ancestorVersion": "HIGHEST",
     "default": true
   }
 ],
 "namespace": "fforce",
 "sfdcLoginUrl": "https://login.salesforce.com",
 "sourceApiVersion": "55.0",
 "packageAliases": {
   "FormulaForce App": "0Ho6A000000CaVxSAK",
   "FormulaForce App@0.1.0-1": "04t6A0000038K3GQAU"
 }
}

Each time you release a version of your package, you must check the preceding process to ensure the intended ancestor is the one you want and make sure the versionName and versionNumber reflect the correct values for your next release. This is a significant part of your release process so be sure to document it carefully along with your other release management tasks.

If you want to create a package version that has no link to past releases, because you want to intentionally create a new lineage that allows you to make more changes to your packages not otherwise permitted, such as renaming components, then you can use the --skipancestorcheck parameter when creating the package. However, keep in mind customers will not be able to upgrade to this version from any prior versions – it is effectively a brand-new package lineage.

You can use the following command to display package ancestry for a given package release. An example output after releasing two more package versions is shown below:

sfdx force:package:version:displayancestry --package "FormulaForce App@2.1.0-1"
2.1.0.2 -> 1.1.0.1 -> 0.1.0.2 (root)

Don’t worry if you forget to manage ancestry throughout the rest of this book as you are only building a sample application and aren’t sharing it with users who will care about upgrades.

For package versions created without ancestry, you will have to either use a new test scratch org to install the new release or uninstall a previous version from an existing test org. This is because the platform will not permit an upgrade to a package already installed in an org if the package being installed does have valid ancestry information, even if it shares the same namespace.

Developing in scratch orgs containing ancestry information

Next time you create a scratch org, you will notice that aspects of the Setup menu are now aware that certain components have been previously released to your customers and will block certain operations that would break upgradability, such as changing the API name or deletion. The following screenshot shows an example of such a notification:

Figure 1.5: Notification that the ability to edit attributes is limited

Of course, there is nothing stopping you from deleting a source file in your local copy of the package that is representing a previously released component, for example, the Team__c folder. If you try this, however, you will get an error during package creation. Either way, when you maintain ancestry information in your sfdx-package.json file, the system protects you from accidental or intentional breaking changes being made to your upgrade path.

If you want to create a scratch org without ancestry information, you can use the --noancestors parameter on the sfdx force:org:create command. This can be useful when creating test orgs (which cannot have the same namespace as installed packages). Finally, keep in mind that the preceding enforcement, when developing in a scratch org with ancestry defined, is advantageous to identify upgrade-breaking changes early in the release cycle. You may want to skip managing ancestry for this book, though it should be considered a good practice when developing for real.