The actual upgrade work is a five-step sequence: read the release notes, install in sandbox, run regression tests, schedule production, and validate post-install. Doing each step in the right order is the difference between an uneventful upgrade and a production support escalation. This routine applies whether you are upgrading a CPQ package, a Marketing Cloud Account Engagement (Pardot) package, an industry cloud add-on, or any AppExchange managed package. Skipping the sandbox step is the most common reason production upgrades fail unexpectedly.
- Read the Publisher release notes
Find the Publisher release notes for the new version. They are typically linked from the AppExchange listing or from the Publisher support site. Read the breaking-changes section first, the new-features section second, and the bug-fixes section last. Capture any items that affect your Subscriber-side customizations (renamed methods, removed fields, behavior changes). If your org has Apex code that extends the package, find every reference to package symbols in your code and compare against the release notes. Skip this step and the rest of the routine is guesswork.
- Install in a sandbox and run regression tests
Refresh a sandbox that has the same configuration and the same Subscriber-side extensions as production. Install the new package version into the sandbox using the AppExchange link or the Publisher install URL. Watch the install log for compilation failures or permission warnings. After install, run your full regression test suite on the affected user journeys. Manual testers should cover the package main flows; automated tests should cover any Apex code that depends on the package. Capture every defect in your tracker and triage them with the Publisher and your dev team before scheduling production.
- Schedule the production upgrade and notify users
Pick a maintenance window when usage is low (overnight or weekend for most orgs). Notify users in advance about the window and any expected behavior changes. On the day, take a metadata snapshot of the production org (a recent change set or DX export) so you have a record of pre-upgrade state. Install the package version in production using the same AppExchange link or install URL you tested with in sandbox. Watch the install log. For Push Upgrades, you do not control the timing; the Publisher pushes when they push.
- Validate post-upgrade and document
After install completes, validate the package by walking through the same regression scenarios you ran in sandbox. Confirm new features show up in the UI, custom code still compiles and runs, and any Publisher-supplied automations fire correctly. Update the org upgrade log with the date, version, and any issues you encountered. Document any new package features for end users (release notes from your side, not the Publisher side). Schedule a one-week monitoring window during which support tickets that mention the upgraded package get routed to a dedicated triage queue.
- Push Upgrades happen without Subscriber action and during Publisher-chosen windows. Disable Push Upgrades on high-risk packages if your change management policy requires advance notice for every install.
- Compilation failures during install trigger an automatic rollback to the prior version. The rollback is data-safe but the error message is technical. Have a developer ready to interpret on the day of the upgrade.
- Salesforce does not support rolling back a successful upgrade. Manual rollback means uninstalling the package and losing data, which is almost never the right answer. Test thoroughly in sandbox first.
- Major version upgrades may change Apex method signatures, schema, or behavior. Read the release notes and update Subscriber-side code in the same release window so production never runs on an inconsistent combination.
- Reports and dashboards built on package data can break if the Publisher removed or renamed an object or field. Inventory dependencies before upgrade and rebuild any reports that break the moment the new version goes live.