We’re starting to figure out Unlocked Packages in Salesforce DX, and finally have a working base version. However, we do plan on breaking out fields, classes, etc to dependent packages as we continue to work.
Is there a process that allows us to safely move a piece of metadata from a package to one of its dependent packages? Since I may have already screwed up with the upload (assuming I can’t safely move fields), what should I do with the existing Unlocked Package I created? As far as I can tell, we can’t delete or modify versions of a package at this time.
The documentation does not seem to be clear on how to do any of this, and I would rather not install a package that will later delete a bunch of custom fields if I make a mistake.
Edit: Also, can we move metadata from a dependent package to a base package as well? This may also become necessary as I continue to build out packages in DX.
John answered the question already very well but I want to draw your attention to this hidden documentation gem by the Packaging PM Dileep Burki. It helped to feel safe with Unlocked Packages.
In those sections, it really describes how and that unlocked packages were designed for such refactorings.
Let’s suppose you have installed ver 1 of your unlocked package pkg1.
As part of refactoring your App, you decide to move some metadata from
pkg1 to a new package pkg2.
You will refactor the package by following these steps:
- Identify the metadata that you want to move out of pkg1.
- Remove metadata identified in step 1 from pkg1 repo and create ver 2 of
- Add the metadata identified in step 1 to a different DX folder
/ project / repo and create ver 1 of pkg2 using that metadata. You
may add other metadata to complete pkg2.
- After proper testing and
UAT, install ver 2 of pkg1 in the org where ver1 of pkg1 has been
- Install ver1 of pkg2 in the same org.
- At the end of step
5, the metadata identified in step 1 would have migrated from pkg1
You should consider any downgrade of a package carefully. Package
downgrades can fail due to dependency scenarios. For E.g.: if ver 3.0
has an apex class that is referenced by another apex class in a
different package, downgrading to ver 2.0 would fail with a
user-friendly error message if that apex class is not present in ver
2.0 of the package.
In the context of packaging, a downgrade is installing a lower version
of a package on top of a higher version. For E.g.: this is when you
try to install ver 2.0 of your package in an org where ver 3.0 has
When you downgrade a package, the following occurs:
- The metadata of the package version (ver 2.0 in this example) is deployed to the target org.
- Any metadata that is present as part of the package in the installed org (ver 3.0 metadata in this example) is modified, deleted or deprecated based on whether they are present in the version being installed. For E.g.: an apex class will be modified to the ver 2.0 copy of it as part of the downgrade. If a custom object foo__c is not present in ver 2.0 but present in ver 3.0, foo__c is marked deprecated (See here for more info about what deprecated means in this context). If a report object is not present in ver 2.0 but present in ver 3.0, the report is deleted from the org.