Source Decomposition Options for CustomLabels

[VivekMChawla]

Please help validate (or improve!) the design for decomposing CustomLabels

We are finalizing the design of a new source behavior option for CustomLabels.

If enabled, the optional behavior applies a new "decomposition" strategy when CustomLabels.labels metadata is converted to "source format" inside the packageDirectories of an SFDX project.

Ready to help?

1. Review the proposed source behavior (posted below)
2. Vote in the poll (directly below)
3. Comment with your feedback/questions (optional)

Want to understand what's changing?

• You may find it helpful to compare the proposed design to the default source behavior (posted further below)

Thank you for voting!

[VivekMChawla]

Proposed Source Behavior

• The proposed source behavior is optional.
• Your source files will not change unless you explicitly activate this feature.
• There are no plans to deprecate the current (default) source behavior.

Proposed Source FILE Behavior

• Individual CustomLabel components appear once per file in dedicated *.label-meta.xml source files.
• The name of each *.label-meta.xml source file is derived from the fullName of the CustomLabel component it contains.
  • For example, the CustomLabel component named Login_Message is defined by a source file named Login_Message.label-meta.xml.

Proposed Source FOLDER Behavior

• All *.label-meta.xml source files must be contained by a labels source directory.
• Multiple labels source directories can be present in an SFDX project and exist in multiple package directories.
• Subdirectories can be used to further organize *.label-meta.xml files inside of a labels source directory.
  • This is optional, at the discretion of the user

Examples of Proposed Source Behavior

1. CustomLabel components retrieved to the default package directory

sfdx-project 
 └─ force-app
     └─ main
         └─ default
             └─ labels
                 ├─ Login_Message.label-meta.xml  
                 ├─ Logout_Message.label-meta.xml
                 ├─ Authentication_Error.label-meta.xml
                 └─ Timeout_Warning.label-meta.xml

2. CustomLabel components organized outside of the default package directory

sfdx-project 
 ├─ force-app
 └─ otherPackageDir
     └─ labels
         ├─ Login_Message.label-meta.xml  
         ├─ Logout_Message.label-meta.xml
         ├─ Authentication_Error.label-meta.xml
         └─ Timeout_Warning.label-meta.xml

3. CustomLabel components organized further using a subdirectory

sfdx-project 
 ├─ force-app
 └─ otherPackageDir
     └─ labels
         ├─ Application
         │   ├─ Login_Message.label-meta.xml  
         │   └─ Logout_Message.label-meta.xml
         ├─ Authentication_Error.label-meta.xml
         └─ Timeout_Warning.label-meta.xml

4. CustomLabel components organized in multiple package directories and subdirectories

sfdx-project 
 ├─ force-app
 │   └─ main
 │       └─ default
 │           └─ labels
 │               ├─ Login_Message.label-meta.xml  
 │               └─ Logout_Message.label-meta.xml
 └─ otherPackageDir
     └─ labels
         ├─ Error
         │   └─ Authentication_Error.label-meta.xml
         └─ Warning
             └─ Timeout_Warning.label-meta.xml

↑ Cast Your Vote ↑

[VivekMChawla]

Default Source Behavior

This section documents the default source behavior for CustomLabels.labels metadata.

Default Source FILE Behavior

• Individual CustomLabel components may appear in multiple *.labels-meta.xml source files.
  • The default Custom Labels source file is CustomLabels.labels-meta.xml.
  • This name can be changed without impacting source deploy/retrieve behavior.
• Each CustomLabel component inside a *.labels-meta.xml file must have a unique fullName within the SFDX project.
  • Deploying components with duplicate fullName values results in an error.

Default Source FOLDER Behavior

• All *.labels-meta.xml source files must be directly contained in a labels source directory.

Examples of Default Source Behavior

1. CustomLabel components retrieved to the default package directory

sfdx-project 
 └─ force-app 
     └─ main
         └─ default
             └─ labels
                 └─ CustomLabels.labels-meta.xml  // Has ALL CustomLabel components

2. CustomLabel components in multiple package directories using custom file names

sfdx-project 
 ├─ force-app
 │    └─ main
 │        └─ default
 │            └─ labels
 │                └─ CustomLabels.labels-meta.xml  // Has Login_Message & Logout_Message components
 └─ otherPackageDir
     └─ labels
         ├─ Error.labels-meta.xml        // Has Authentication_Error component
         └─ Warning.labels-meta.xml      // Has Timeout_Warning component

↑ Cast Your Vote ↑

[nvuillam]

Will this impact the number of deployed items ?
(+ 2000 could be a problem for CI/CD on big orgs ^^)

[mcarvin8]

I've definitely seen this issue with decomposing permission sets in my work's large org while using Salesforce's decomposition strategy since their beta supports permission sets. I've had issues using the beta with retrieving decomposed permission sets due to the size of the request.

My sf-decomposer plugin doesn't run into that issue since it decomposes after the retrieve is complete (using a post run hook). Since the Salesforce beta decomposes during the request, this might be an issue for any large org with rather large metadata like perm sets.

Haven't had the issue with custom labels. But we only have about 250 labels.

IMO, it would be nice to offer selective decomposition via an ignore file or something else. Salesforce's beta is all or nothing in terms of metadata you opt into decomposition. In my sf-decomposer plugin, I updated it to read an ignore file to allow you to ignore specific files during decomposition. Might help with avoiding large files if you don't want to deal with the hassle. Granted selective decomposition might not be feasible with the custom labels file.

[VivekMChawla]

Will this impact the number of deployed items ?
(+ 2000 could be a problem for CI/CD on big orgs ^^)

@nvuillam - Is your concern related to exceeding MDAPI file count limits? If so, there's no need to worry. Those 2000 *.label-meta.xml source files would always be "recomposed" into a single CustomLabels.labels metadata file for the deployment.

IMO, it would be nice to offer selective decomposition via an ignore file or something else.

@mcarvin8 - Interesting idea. What would an ignore file for CustomLabel decomposition look like in practice? How do you see something like this impacting the decomposed file structure?

I've definitely seen this issue with decomposing permission sets in my work's large org while using Salesforce's decomposition strategy since their beta supports permission sets. I've had issues using the beta with retrieving decomposed permission sets due to the size of the request.

@mcarvin8—Permsets are the next decomposition strategy we'll post for review. Before we do, I'd like to connect with you and hear more about the problems you're seeing.

[aheber]

I think the only concern I have is the scale of large custom labels is up to 5K per org. That is a lot of files to add to the file system and source tracking, both customer tracking and the SF CLI's source tracking. I don't know if that is a serious concern but it is something I would appreciate someone saying "it is totally fine! We've tested it on all of our supported operating systems."

Non-scientific gut feeling you're talking about 10% increase in the number of individual files, based on a few projects I have access to.

[VivekMChawla]

I think the only concern I have is the scale of large custom labels is up to 5K per org. That is a lot of files to add to the file system and source tracking, both customer tracking and the SF CLI's source tracking.

@aheber - This is my concern as well. We considered having a mix of storing individual labels in *.label-meta.xml files and storing "bulk labels" in *.labels-meta.xml (note the s at the end of this one).

Ultimately, we opted for the consistent and predictable behavior that an "all or nothing" approach provides, despite its drawbacks.

For projects with thousands of Custom Labels, the recommendation is to keep the default behavior and use multiple *.labels-meta.xml files to make it easier to work with them in source.

[aheber]

I think that sounds great. Not worse for anyone but for those where it makes sense they can change.
Thanks!

[prakash-purswani]

Can we utilize category field to group them in sub-folders? I know category is a free text field but can be useful. It would be so many files like email template or report folders and difficult to manage.

But any solution would be a big improvement as compared to existing single file approach.

[VivekMChawla]

Can we utilize category field to group them in sub-folders?

@prakash-purswani - Creating sub-folders based on the label's category is a really good idea. The proposed design supports developers doing this themselves, as demonstrated in this example:

sfdx-project 
 ├─ force-app
 │   └─ main
 │       └─ default
 │           └─ labels
 │               ├─ Login_Message.label-meta.xml  
 │               └─ Logout_Message.label-meta.xml
 └─ otherPackageDir
     └─ labels
         ├─ Error                                     <-- This is the "Error" Category
         │   └─ Authentication_Error.label-meta.xml
         └─ Warning                                   <-- This is the "Warning" Category
             └─ Timeout_Warning.label-meta.xml

I'm concerned about the added complexity of the CLI automating the creation of category folders during source decomposition. If we create the folders for you during decomposition, then we're on the hook to ensure they stay in the right folders when categories change.

[VivekMChawla]

Thank you all for voting and commenting.

Based on your feedback, we will move forward with finalizing the proposed source decomposition option for CustomLabels.

I'll now close and unpin this discussion. Thank you!