Managed Packages Deep Dive: Upgrades, Versions, and Namespace Hell

First vs Second Generation Packaging

Salesforce has two managed package generations. First Generation Packaging (1GP) uses a single Developer Edition org as the packaging org. The package namespace is tied to that org, and package versions are created and uploaded from it. 1GP has been the standard since the AppExchange launched and all existing legacy packages use it.

Second Generation Packaging (2GP) is the modern approach, introduced with Salesforce DX. Packages are defined in source code as sfdx-project.json artifacts and versions are created via the CLI using scratch orgs. 2GP supports modular package structures, beta/release tracks, and source-controlled versioning. New ISV development should use 2GP.

Namespace Prefixes: The Permanent Scar

When a managed package is installed, every API component it introduces gets a namespace prefix: mynamespace__FieldName__c, mynamespace__MyObject__c, mynamespace__MyClass. This prefix is permanent — it cannot be changed or removed after the package is installed, and it affects every SOQL query, Apex reference, and integration mapping that touches those fields.

The implications for architects:

• SOQL queries must include the namespace prefix for package fields: SELECT mynamespace__Status__c FROM mynamespace__Order__c
• Integration field maps break when a new package is installed that adds a prefix to previously namespace-free fields
• Multiple packages with overlapping concept names create visual noise: pkg1__Status__c vs pkg2__Status__c vs Status__c all appearing on the same record page

// Namespace prefix in SOQL
SELECT Id,
       pkg1__ContractStatus__c,
       pkg2__SLALevel__c,
       Internal_Status__c          -- no prefix: customer-owned field
FROM Account
WHERE pkg1__ContractStatus__c = 'Active'

// Namespace prefix in Apex
pkg1.ContractService.createContract(acct);  // calling package class
pkg1__Contract__c contract = new pkg1__Contract__c();  // package object

// Checking installed packages programmatically
List<PackageLicense> pkgs = [
  SELECT NamespacePrefix, AllowedLicenses, UsedLicenses
  FROM PackageLicense
];

The Upgrade Model: Push vs Pull

Managed package upgrades come in two delivery mechanisms:

Pull upgrades: The subscriber visits AppExchange and installs the new package version manually. The subscriber controls the timing. Most packages use this model.

Push upgrades: The ISV pushes a new version to subscriber orgs on a scheduled date. The subscriber receives advance notice but cannot defer. Salesforce itself uses push upgrades for security-critical package updates. Some third-party ISVs have negotiated push upgrade rights with their customers.

The risk profile is different. Pull upgrades give full control to the subscriber but create version fragmentation — if subscribers delay for 12+ months, the ISV must support too many versions. Push upgrades reduce fragmentation but can break customer customisations without warning.

Deprecation vs Deletion: The Safe Removal Rules

A managed package ISV cannot delete a field, class, or object that has been released in a managed version — deletion is permanent and could break any subscriber that references that component. The approved pattern is deprecation:

• Mark the component as deprecated in the packaging org using the @deprecated Apex annotation or the field's "Deprecated" status.
• Ship a new package version. Deprecated components remain in subscriber orgs but are not visible in new orgs receiving a fresh install.
• Communicate the deprecation in release notes with a removal timeline (typically 2+ major versions in the future).

Subscribers who reference deprecated components should migrate to the replacement before the hard-removal version is released. ISVs that skip this process and attempt forced removal break subscriber orgs — a violation of the AppExchange agreement.

Architecting Customisations That Survive Upgrades

Customisations that survive package upgrades share these patterns:

• Extension over override: Extend package Apex classes using virtual/global overrides rather than replacing package logic. Overrides that call super methods will automatically benefit from upstream changes to the parent class.
• Loose coupling to package fields: Where possible, map package fields to your own custom fields via automation rather than directly referencing package fields in reports, integrations, and UI. When the package field is renamed or deprecated, update the mapping in one place.
• Test against beta versions: Install package beta versions in a sandbox 2-4 weeks before the ISV's production release. Run your full regression suite. Communicate failures to the ISV before the release ships.
• Version-pin your references: In Apex that calls package APIs, document the minimum package version your code was tested against. When upgrading, re-test those specific integrations first.