docs: add table of contents and sections

mcarvin8 · Nov 21, 2024 · 3c4d154 · 3c4d154
1 parent d74cacf
commit 3c4d154
Showing 1 changed file with 60 additions and 21 deletions.
diff --git 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 `<name>` elements with the metadata name will be converted to lower-case, ex: `<name>customobject</name>`. 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 `<name>` elements are case insensitive when read by the Salesforce CLI. However, the `<members>` elements are case sensitive and their cases must match their API names in Salesforce. This tool will not convert the cases of the `<members>` elements, just the `<name>` elements.
-
-The combined package.xml will use the maximum `<version>` tag found in all packages. If none of the packages provided have `<version>`, 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 -->
+<details>
+  <summary>Table of Contents</summary>
+
+- [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)
+</details>
 
-Salesforce packages follow this structure:
-
-- `<Package xmlns="http://soap.sforce.com/2006/04/metadata">`: Root element must be `Package` with the Salesforce namespace.
-    - `<types>`: 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.
-      - `<members>`: 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 `<types>`.
-      - `<name>`: Specifies the type of metadata, such as "ApexClass", "ApexTrigger", or "CustomObject". Must be declared only once in each `<types>` element.
-    - `<version>`: 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
 
 <!-- commandsstop -->
 
-## Parsing Strings with `package.xml` contents
+## How the Packages Are Combined
+
+When the packages are combined, the `<name>` elements with the metadata name will be converted to lower-case, ex: `<name>customobject</name>`. 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 `<name>` elements are case insensitive when read by the Salesforce CLI. However, the `<members>` elements are case sensitive and their cases must match their API names in Salesforce. This tool will not convert the cases of the `<members>` elements, just the `<name>` elements.
+
+The combined package.xml will use the maximum `<version>` tag found in all packages. If none of the packages provided have `<version>`, 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 `<types>` 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 '<types>' ./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:
+
+- `<Package xmlns="http://soap.sforce.com/2006/04/metadata">`: Root element must be `Package` with the Salesforce namespace.
+    - `<types>`: 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.
+      - `<members>`: 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 `<types>`.
+      - `<name>`: Specifies the type of metadata, such as "ApexClass", "ApexTrigger", or "CustomObject". Must be declared only once in each `<types>` element.
+    - `<version>`: 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.