From 3c4d15461e483118c9f465f7bd8c1f906dab5359 Mon Sep 17 00:00:00 2001 From: Matt Carvin <90224411+mcarvin8@users.noreply.github.com> Date: Thu, 21 Nov 2024 11:18:11 -0500 Subject: [PATCH] docs: add table of contents and sections --- README.md | 81 ++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 60 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 3e57517..3f41ea2 100644 --- a/README.md +++ b/README.md @@ -2,27 +2,21 @@ [![NPM](https://img.shields.io/npm/v/sf-package-combiner.svg?label=sf-package-combiner)](https://www.npmjs.com/package/sf-package-combiner) [![Downloads/week](https://img.shields.io/npm/dw/sf-package-combiner.svg)](https://npmjs.org/package/sf-package-combiner) [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://raw.githubusercontent.com/mcarvin8/sf-package-combiner/refs/heads/main/LICENSE.md) -A Salesforce CLI plugin to combine multiple manifest files (package.xml) into 1 file that can be used for deployments. - -When the packages are combined, the `` elements with the metadata name will be converted to lower-case, ex: `customobject`. This ensures that multiple members of the same metadata name are grouped together in the combined package and that duplicate members are only declared once. The `` elements are case insensitive when read by the Salesforce CLI. However, the `` elements are case sensitive and their cases must match their API names in Salesforce. This tool will not convert the cases of the `` elements, just the `` elements. - -The combined package.xml will use the maximum `` tag found in all packages. If none of the packages provided have ``, it will omit this from the combined package.xml. When you deploy a package.xml without an API version, it will check the `sfdx-project.json` file for the `sourceApiVersion`. If both files do not have an API version, it will follow the [sourceApiVersion: Order of Precedence](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_apiversion.htm). - -The packages provided must match the expected Salesforce package.xml structure. If you provide an XML which doesn't match the expected structure, it will print this warning and not add it to the output: - -``` -Warning: File .\test\samples\pack2.xml does not match expected Salesforce package structure. -``` - -If all packages provided don't match the expected structure, the combined package.xml will be an empty package. + +
+ Table of Contents + +- [Install](#install) +- [Command](#command) + - [`sf-sfpc-combine`](#sf-sfpc-combine) +- [How the Packages Are Combined](#how-the-packages-are-combined) +- [Salesforce Package Structure](#salesforce-package-structure) +- [Parsing Strings with Package Contents](#parsing-strings-with-package-contents) +- [Issues](#issues) +- [License](#license) +
-Salesforce packages follow this structure: - -- ``: Root element must be `Package` with the Salesforce namespace. - - ``: This element defines a specific type of metadata component. It is used to group components of the same type, such as Apex classes, triggers, or Visualforce pages. Can be declared multiple times, but must be declared at least once. - - ``: Lists the individual components by their API names within that type. Multiple members can be included under the same type but at least 1 member must be declared in each ``. - - ``: Specifies the type of metadata, such as "ApexClass", "ApexTrigger", or "CustomObject". Must be declared only once in each `` element. - - ``: This optional element specifies the API version of Salesforce metadata that you are working with. It helps ensure compatibility between your metadata and the version of Salesforce you're interacting with. This can only be declared once. +A Salesforce CLI plugin to combine multiple manifest files (package.xml) into 1 file that can be used for deployments. ## Install @@ -72,7 +66,44 @@ EXAMPLES -## Parsing Strings with `package.xml` contents +## How the Packages Are Combined + +When the packages are combined, the `` elements with the metadata name will be converted to lower-case, ex: `customobject`. This ensures that multiple members of the same metadata name are grouped together in the combined package and that duplicate members are only declared once. The `` elements are case insensitive when read by the Salesforce CLI. However, the `` elements are case sensitive and their cases must match their API names in Salesforce. This tool will not convert the cases of the `` elements, just the `` elements. + +The combined package.xml will use the maximum `` tag found in all packages. If none of the packages provided have ``, it will omit this from the combined package.xml. When you deploy a package.xml without an API version, it will check the `sfdx-project.json` file for the `sourceApiVersion`. If both files do not have an API version, it will follow the [sourceApiVersion: Order of Precedence](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_apiversion.htm). + +The packages provided must match the expected Salesforce package.xml structure. If you provide an XML which doesn't match the expected structure, it will print this warning and not add it to the output: + +``` +Warning: File .\test\samples\pack2.xml does not match expected Salesforce package structure. +``` + +If all packages provided don't match the expected structure, the combined package.xml will be an empty package. + +You can avoid deploying an empty package by searching the package for any `` elements in it. + +``` bash +# run deploy command only if the combined package contains metadata +sf sfpc -f package/package.xml -f package.xml -c package.xml +if grep -q '' ./package.xml ; then + echo "---- Deploying added and modified metadata ----" + sf project deploy start -x package.xml +else + echo "---- No changes to deploy ----" +fi +``` + +## Salesforce Package Structure + +Salesforce packages follow this structure: + +- ``: Root element must be `Package` with the Salesforce namespace. + - ``: This element defines a specific type of metadata component. It is used to group components of the same type, such as Apex classes, triggers, or Visualforce pages. Can be declared multiple times, but must be declared at least once. + - ``: Lists the individual components by their API names within that type. Multiple members can be included under the same type but at least 1 member must be declared in each ``. + - ``: Specifies the type of metadata, such as "ApexClass", "ApexTrigger", or "CustomObject". Must be declared only once in each `` element. + - ``: This optional element specifies the API version of Salesforce metadata that you are working with. It helps ensure compatibility between your metadata and the version of Salesforce you're interacting with. This can only be declared once. + +## Parsing Strings with Package Contents Currently, I'm working on a feature to allow strings containing package.xml contents to be accepted through the terminal using a new command flag. @@ -112,3 +143,11 @@ if [[ "$PACKAGE_FOUND" == "True" ]]; then sf sfpc combine -f "package/package.xml" -f "$DEPLOY_PACKAGE" -c "$DEPLOY_PACKAGE" fi ``` + +## Issues + +If you encounter any issues, please create an issue in the repository's [issue tracker](https://github.com/mcarvin8/sf-package-combiner/issues). + +## License + +This project is licensed under the MIT license. Please see the [LICENSE](https://raw.githubusercontent.com/mcarvin8/sf-package-combiner/main/LICENSE.md) file for details.