Create and manage Package Versions

Working with Package Versions spans the developer-side creation workflow, the testing and promotion workflow, and the ongoing version-lifecycle management. The walkthrough below covers the standard sequence for releasing a new package version from a Salesforce DX project.

1. 1
   Set the target version in sfdx-project.json

   Update the project's sfdx-project.json file to set the new version number. The versionNumber field follows the major.minor.patch.NEXT pattern, where NEXT auto-increments the build number during package version creation. Increment the major, minor, or patch number based on the nature of the changes per semantic versioning. Document the version's changes in a changelog before building.

2. 2
   Build the new package version

   Run sf package version create with the appropriate flags: the package alias, version number override if needed, the ancestor version, any test running options. The command validates the source, runs the configured tests, and produces a beta version with a 04t Id. The build can take minutes to hours depending on the package size and test complexity. Capture the 04t Id; this is the package version's unique identifier.

3. 3
   Test the beta version in scratch orgs and sandboxes

   Install the beta version in scratch orgs that simulate customer environments. Run the standard test scenarios: install on a clean org, install on an org with the previous version (upgrade test), exercise all major features, verify that any breaking changes are documented and acceptable. Engage pilot customers if appropriate. Iterate on the version with additional beta builds if bugs surface. The testing burden is what gates the promotion to released; do not rush this step.

4. 4
   Promote to released and distribute

   Once the beta version passes all testing, run sf package version promote to mark it as released. The version becomes immutable. Update the AppExchange listing or internal distribution channels with the new install URL. Communicate the release to subscribers through the standard channels. Schedule the retirement of older versions on a defined cadence. The new version is now the canonical install for new customers, with existing customers choosing when to upgrade.