[Wiki] Decision support for publishing target locations

docs/wiki/Getting started - Scenario 2 Onboard module library and CI environment.md

@@ -208,6 +208,8 @@ The primary pipeline variable file ([`global.variables.yml`](https://github.com/
 
 > **NOTE:** If you plan to use the private container registry for Bicep, make sure to update its value in `bicepRegistryName`, as it must be globally unique.
 
+> **NOTE:** If you are uncertain which publishing option to choose, [this section](./Solution%20creation#publish-location-considerations) may be of help.
+
 ### 3.2.3 Enable actions
 
 Finally, 'GitHub Actions' are disabled by default and hence, must be enabled first.
@@ -329,6 +331,8 @@ The primary pipeline variable file ([`global.variables.yml`](https://github.com/
 
 > **NOTE:** If you plan to use the private container registry for Bicep, make sure to update its value in `bicepRegistryName` as it must be globally unique.
 
+> **NOTE:** If you are uncertain which publishing option to choose, [this section](./Solution%20creation#publish-location-considerations) may be of help.
+
 ### 3.2.4 Register pipelines
 
 To use the pipelines that come with the environment in Azure DevOps, you need to register them first. You can either do this manually, or, run the utility `Register-AzureDevOpsPipeline` we provide in `utilities/tools/AzureDevOps`. For further information, please refer to the corresponding [documentation](./Interoperability%20-%20Register%20Azure%20DevOps%20Pipelines).

docs/wiki/Solution creation.md

@@ -8,6 +8,7 @@ This section shows you how you can orchestrate a deployment using multiple resou
 
 - [Upstream workloads](#upstream-workloads)
 - [Orchestration overview](#orchestration-overview)
+  - [Publish-location considerations](#publish-location-considerations)
 - [Template-orchestration](#template-orchestration)
   - [How to start](#how-to-start)
   - [Examples](#examples)
@@ -43,6 +44,55 @@ Both the _template-orchestration_, as well as _pipeline-orchestration_ may run a
 
    <img src="./media/SolutionCreation/pipelineOrchestration.png" alt="Pipeline orchestration" height="400">
 
+## Publish-location considerations
+
+For your solution, it is recommended to reference modules from a published location, to leverage versioning and avoid the risk of breaking changes. 
+
+CARML supports publishing to different locations, either through the use of the CI environment or by locally running the same scripts leveraged by the publishing step of the CI environment pipeline, as explained next.
+
+In either case, you may effectively decide to configure only a subset of publishing locations as per your requirements.
+
+To help you with the decision, the following content provides you with an overview of the possibilities of each target location.
+
+### Outline
+- **Template Specs**<p>
+  A [Template Spec](https://docs.microsoft.com/en-us/azure/azure-resource-manager/templates/template-specs?tabs=azure-powershell) is an Azure resource with the purpose of storing & referencing Azure Resource Manager (ARM) templates. <p>
+  When publishing Bicep modules as Template Specs, the module is compiled - and the resulting ARM template is uploaded as a Template Spec resource version to a Resource Group of your choice.
+  For deployment, it is recommended to apply a [template-orchestrated](#Orchestration-overview) approach. As Bicep supports the Template-Specs as linked templates, this approach enables you to fully utilize Azure's parallel deployment capabilities.
+  > **Note:** Even though the published resource is an ARM template, you can reference it in you Bicep template as a remote module like it would be native Bicep.
+  > **Note:** Template Spec names have a maximum of 90 characters
+
+- **Bicep Registry**<p>
+  A [Bicep Registry](https://docs.microsoft.com/en-us/azure/azure-resource-manager/bicep/private-module-registry) is an Azure Container Registry that can be used to store & reference Bicep modules.<p>
+  For deployment, it is recommended to apply a [template-orchestrated](#Orchestration-overview) approach. As Bicep supports the Bicep registry as linked templates, this approach enables you to fully utilize Azure's parallel deployment capabilities.
+
+- **Azure DevOps Universal Packages**<p>
+  A [Universal Package](https://docs.microsoft.com/en-us/azure/devops/artifacts/quickstarts/universal-packages) is a packaged folder in an Azure DevOps artifact feed.<p>
+  As such, it contains the content of a CARML module 'as-is', including the template file(s), ReadMe file(s) and test file(s). <p>
+  For deployment, it is recommended to use Universal Packages only for a [pipeline-orchestrated](#Orchestration-overview) approach - i.e., each job would download a single package and deploy it. <p>
+  Technically, it would be possible to also use Universal Packages for the template-orchestrated approach, by downloading all packages into a specific location first, and then reference them. Given the indirect nature of this approach, this is however not recommended. (:large_orange_diamond:)
+  > **Note:** Azure DevOps Universal Packages enforce _semver_. As such, it is not possible to overwrite an existing version.
+
+### Comparison
+
+The following table provides you with a comparison of the locations described above:
+
+| Category | Feature | Template Specs | Bicep Registry | Universal Packages |
+| - | - | - | - | - |
+| Portal/UI |
+| | Template can be viewed |:white_check_mark: | | |
+| | Template can be downloaded | | | |
+| |
+| Deployment |
+| | Supports [template-orchestration](./Solution%20creation#Orchestration-overview) | :white_check_mark: | :white_check_mark: | :large_orange_diamond: |
+| | Supports [pipeline-orchestration](./Solution%20creation#Orchestration-overview) | :white_check_mark: | :white_check_mark: | :white_check_mark:  |
+| | Supports single endpoint | | :white_check_mark: | :white_check_mark: |
+| |
+| Other |
+| | Template can be downloaded/restored via CLI | :white_check_mark: | :white_check_mark: | :white_check_mark: |
+| | Allows referencing latest [minor](./The%20CI%20environment%20-%20Publishing#how-it-works) | :white_check_mark: | :white_check_mark: | |
+| | Allows referencing latest [major](./The%20CI%20environment%20-%20Publishing#how-it-works) | :white_check_mark: | :white_check_mark: | :white_check_mark: |
+
 # Template-orchestration
 
 The _template-orchestrated_ approach means using a _main_ or so-called _master template_ for deploying resources in Azure. This template will only contain nested deployments, where the modules - instead of directly embedding their content into the _master template_ - will be referenced by the _master template_.

docs/wiki/The CI environment - Publishing.md

@@ -10,16 +10,18 @@ This section provides an overview of the principles the publishing is built upon
 # Publishing overview
 The publishing phase concludes each module's pipeline. If all previous tests succeed (i.e., no phase failed) and the pipeline is run in the `main` or `master` branch, a new module version is published to all configured target locations. Currently, we support the following target locations:
 
-- _[Template specs](https://docs.microsoft.com/en-us/azure/azure-resource-manager/templates/template-specs?tabs=azure-powershell)_
-- _[Private Bicep registry](https://docs.microsoft.com/en-gb/azure/azure-resource-manager/bicep/private-module-registry)_
-- _[Azure DevOps universal packages](https://docs.microsoft.com/en-us/azure/devops/artifacts/concepts/feeds?view=azure-devops)_.
+- _[Template Specs](https://docs.microsoft.com/en-us/azure/azure-resource-manager/templates/template-specs?tabs=azure-powershell)_
+- _[Bicep Registry](https://docs.microsoft.com/en-gb/azure/azure-resource-manager/bicep/private-module-registry)_
+- _[Azure DevOps Universal Packages](https://docs.microsoft.com/en-us/azure/devops/artifacts/concepts/feeds?view=azure-devops)_.
    > Note: this is only available if using Azure DevOps pipelines.
 
 Besides the publishing phase's runtime, there is also the possibility to set the switch `Publish prerelease module`. This switch makes it possible to publish a prerelease version in every workflow run that is not based on `main` or `master`. This can be controlled when running the module pipeline leveraging [Module pipeline inputs](./The%20CI%20environment%20-%20Pipeline%20design#module-pipeline-inputs).
 
 > **Note**<br>
 > The `version` used for publishing any artifact is the same for all three target locations, which reduces the maintenance effort.
 
+> **Note:** The orchestration options described in the [solution creation](./Solution%20creation) section work differently well with the publishing locations we offer in CARML. To help you select the best location for your use case, we provide further information [here](./Solution%20creation#publish-location-considerations) section.
+
 # How it works
 
 The publishing works as follows:

docs/wiki/The context - CARML CI environment.md

@@ -68,4 +68,6 @@ From left to right, there are the three phases introduced before, _Develop modul
    - _[Azure DevOps Universal Packages](https://docs.microsoft.com/en-us/azure/devops/artifacts/concepts/feeds?view=azure-devops)_.
      > Note: this is only available if using Azure DevOps pipelines.
 
+   To dive deeper and understand which target locations may be best suited for your use case, we provide further information in the [Publish-location considerations](./Solution%20creation#publish-location-considerations) section.
+
 1. The third phase, **Consume modules** is represented on the right. The top right corner provides examples of orchestrations deploying the target solutions by referencing the published modules. The deployments performed in this third phase are supposed to target an integration/production environment. This phase references the validated and published modules coming out of the CARML CI environment, and leverages them with the correctly configured parameters to orchestrate their deployment in the intended order.