Creating a 2GP patch means producing a package version that bumps only the patch segment of an already-released major.minor line, then promoting it for customers. There is no patch org. You work from source and the Salesforce CLI.
- Confirm the released base version
Identify the released major.minor version you need to fix, for example 2.5. The patch must target an existing released line and respect package ancestry, so verify the base version exists and is promoted before you start.
- Set the patch version number
In sfdx-project.json, set versionNumber for the package directory to the next patch, such as 2.5.1.NEXT. Keep major and minor identical to the base. NEXT lets the CLI assign the build number automatically.
- Make only fix-shaped changes
Commit the bug fix to your source. Keep the change minor and corrective. Adding broad new functionality belongs in a minor or major version, and the CLI will reject a patch that steps outside those bounds.
- Create the patch package version
Run the Salesforce CLI package version create command against your Dev Hub. It reads the version number from sfdx-project.json, builds the version from source, and runs validation including Apex tests.
- Promote and deliver
Promote the version from beta to released, then give subscribers the install link or push the upgrade to installed orgs. Customers on the base version take the patch as a small upgrade.
The major.minor.patch.build value in sfdx-project.json. For a patch, only the patch segment increases; build can be NEXT.
The org that owns your packages and creates versions. The CLI targets it to build and store the patch version.
The chain linking a new version to prior ones. A patch must respect ancestry so upgrades stay valid for installed subscribers.
Moving a version from beta to released. Only a released patch can be installed by customers in production orgs.
- A patch cannot change the major or minor number. If your fix needs those to move, it is no longer a patch.
- The CLI blocks patches that add sweeping new functionality. Reserve those changes for a minor or major version.
- Patches respect package ancestry. Skipping or breaking the ancestry chain can leave subscribers unable to upgrade cleanly.
- In first-generation packaging, patches still require a separate patch development org. Only 2GP removes that requirement.