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 Lightning Platform manages package upgrades for you, without asking users to log out of the system or experience any interruption.

Salesforce DX managed 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

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 ancestorId. The ID to be used is actually the 05i ID of your desired released package version. To retrieve this, run the following command:

sfdx force:package:version:report 
  --package "FormulaForce [email protected]" 
  --verbose

An example output from the preceding command is shown here:

=== Package Version
Name                          Value
───────────────────────────── ──────────────────
Name                          ver 0.1
Subscriber Package Version Id 04t6A0000038K3GQAU
Id                            05i6A000000XZLyQAO
Package Id                    0Ho6A000000CaVxSAK
Version                       0.1.0.1
Description
Branch
Tag
Released                      true

Next, add the ancestorId configuration to the sfdx-package.json file as shown here:

{
 "packageDirectories": [
 {
 "path": "force-app",
 "package": "FormulaForce App",
 "versionName": "ver 0.1",
 "versionNumber": "0.1.0.NEXT",
 "ancestorId": "05i6A000000XZLyQAO",
 "default": true
 }
 ],
 "namespace": "fforce",
 "sfdcLoginUrl": "https://login.salesforce.com",
 "sourceApiVersion": "45.0",
 "packageAliases": {
 "FormulaForce App": "0Ho6A000000CaVxSAK",
 "FormulaForce [email protected]": "04t6A0000038K3GQAU"
 }
}

Each time you release a version of your package, you must repeat the preceding process. This is a significant part of your release process so be sure to document it carefully along with your other release management tasks.

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:

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.