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.

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 [email protected]": "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 [email protected]"
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.

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.