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.

Table of Contents for Managing package ancestry

Create new playlist

Sign In

Sign Up

Table of Contents for
Managing package ancestry