When is it correct to use a <fullName> tag in a package.xml? What is the benefit of 'naming' an unmanaged package?

Question

I am working on a project that involves deploying a sequence of Managed Packages and unmanaged packages (using an ant deployment).

As I was onboarded to the project, I noticed the unmanaged package.xml with the unmanaged metadata had a <fullName> field. This naming convention is causing an issue when we try to deploy certain metadata changes to items that came from the managed package.

Example:

1. Managed Package is deployed into the org with a report folder (NAMESPACE__Managed_Report_Folder)
2. Unmanaged package (with fullName field) is trying to update the managed report folder by granting shares to a public group in the meta.xml file for the report folder
3. When using ant to deploy the unmanaged package, I receive the following error:

Error: Cannot add component of type:ReportFolder named:NAMESPACE__Managed_Report_Folder subjectId:SOME_FOLDER_ID to another package because it is an installed component.

So this begs the question: Can I somehow avoid this error when deploying my unmanaged metadata?

Is the only solution to remove the fullName field in the package.xml?

When should I be using a fullName field in my package vs not including that field and what is the benefit I get out of including a fullName for my package.xml?

Any help is much appreciated!

Answer 1

For a metadata Package, if you do not include the fullName field, it is a simple "unpackaged metadata deployment." If you include the fullName field, it becomes a "unmanaged package deployment."

The difference is that including the fullName field will create or update a package that can be found in the Package Manager area in Setup. This has an advantage of appearing in Setup and showing you all of the components of the package. It has the downside of requiring that the package is "complete", with no missing metadata, as it can later be uploaded as an Unmanaged or Managed Package (depending on the org's settings).

You're limited to what you can put into an Unmanaged Package, because this will create dependencies, which is not ideal for a package that cannot be upgraded. If you're interested in package-based deployments, consider using Unlocked Packages, instead. They behave like Managed Packages, but with more flexibility (e.g. the ability to remove components), and can have dependencies on other Unlocked and Managed Packages (e.g. adding to a report folder, as you're trying to do here).

However, this will require a migration of both metadata and tools, as the old Ant scripts don't support this new paradigm. You can still use Ant, but it would act as a glorified Makefile for the purposes of utility, and it'd be easier to simply migrate to a Node package.json set ot scripts instead.