Apex Version Settings in Migrated Second-Generation Managed Packages (2GP)

The following Apex behaviors in migrated managed 2GP are consistent with those of 1GP.

• If publishing a new version of a migrated managed 2GP, package developers can use the @Deprecated annotation on Apex identifiers that can no longer be referenced in subsequent releases of the managed package. These identifiers include Apex methods, classes, exceptions, enums, interfaces, and variables. All @Deprecated rules are enforced. For example, package developers can’t undeprecate an Apex identifier after releasing a package version where that item is deprecated. See Deprecating Apex in the Apex Developer Guide.

• If a package developer deprecates a global Apex identifier in a migrated managed 2GP, subscribers can only reference that identifier if they specify a package version between the creation and the deprecation of the identifier. This behavior applies to both static and dynamic references, such as identifiers accessed with the Type.forName() method, the instanceof keyword, and the ApexTypeImplementor object.

• Similarly, if a package developer deletes a schema from a migrated managed 2GP, subscriber orgs can only reference the schema in Apex if they specify a package version before the deletion of the schema. This behavior applies to both static and dynamic references, such as objects and fields accessed with Schema.describe() methods.

Potential Issue with Version Settings Created Before Summer ’25

If a package subscriber has used version settings to extend the functionality of an installed 1GP managed package containing Apex or Visualforce components before Summer ’25, and then upgrades to a migrated managed 2GP, their existing version settings remain valid. 

To allow backwards compatibility, <namespace> in <packageVersion> tags will be supported for metadata deploy and retrieve related to migrated 2GP packages. If the subscriber retrieves metadata using API version 61.0 and earlier, <namespace> is used in the <packageVersions> section of the meta.xml file to identify the referenced package.

If the subscriber retrieves metadata using API version 62.0 and later, the <packageId> tag for 2GP package is specified in the <packageVersions> section. An error will occur if attempting to deploy metadata with the <packageId> to an org that still has the 1GP or 2GP pre-migrated version of the package installed. 

To resolve this issue, the subscriber must either upgrade the target org to the migrated package, or edit their <packageVersions> tag to use <namespace>.