Wiki restructuring - Contribution guide

docs/wiki/Contribution guide - Contribution flow.md

@@ -0,0 +1,79 @@
+This section outlines the contribution flow to the CARML repository.
+
+Depending on the contribution, the number and execution of the required below steps may vary.
+
+---
+
+### _Navigation_
+
+- [Create or pick up an issue](#Create-or-pick-up-an-issue)
+- [Environment setup](#Environment-setup)
+- [Implement the contribution](#Implement-the-contribution)
+- [Validate the contribution](#Validate-the-contribution)
+- [Open a PR](#Open-a-PR)
+
+---
+
+# Create or pick up an issue
+
+We kindly ask to have an issue mapped to the contribution you'd like to make.
+How you proceed from here depends on the scenario:
+
+- If you just want to contribute to this project, but don't know yet where and how, feel free to navigate the the 'Projects' tab on the repository, check what items are currently still in the 'to-do' swim lane and pick one that speaks to you. In this case you should assign the item to yourself / or reach out to discuss its content & priority.
+
+   <img src="./media/projectsTab.jpg" alt="Projects Tab" height="178" width="414">
+
+  > Note: For starters we suggest to search for issues labelled with `good first issue`.
+
+- If you find a bug or have an idea that you'd also like to work on, feel free to create an issue in the corresponding GitHub section, assign it to yourself and the project and get started.
+
+  > Note: If you don't feel like working on that alone, you can label the issue with `help wanted` to let the community know.
+
+# Environment setup
+
+The preferred method of contribution requires you to create your own fork and create pull requests into the source repository from there. To set the fork up, please follow the process described in the ['Getting started - Setup environment'](./Getting%20started%20-%20Setup%20environment) section.
+
+How you proceed from here depends on the scenario:
+
+- In case you want to contribute to the documentation, you can limit the setup to forking the repository and cloning your fork locally.
+
+- In case your contribution involves changes to the library (the modules) and/or to the CI environment (the pipelines), you need to setup the full environment, such as GitHub secrets and token replacement, as detailed in the ['Getting started'](./Getting%20started) section and related sub-pages. This will allow you to test your changes against your environment before requesting to merge them to the main repo.
+
+# Implement the contribution
+
+How you proceed from here depends on the scenario:
+
+- In case you want to contribute to the CARML Wiki, your updates need to happen through the main repo under the [docs/wiki](https://github.com/Azure/ResourceModules/tree/main/docs/wiki) folder. A dedicated pipeline included in the repository will perform a sync to the CARML Wiki once the docs contribution is merged.
+
+- In case your contribution involves changes to the library (the modules) and/or to the CI environment (the pipelines), we kindly ask you to
+first review respectively the [Module design](./The%20library%20-%20Module%20design) and/or the [Pipeline design](./The%20CI%20environment%20-%20Pipeline%20design) sections to make sure your contribution complies with the repository design and principles.
+
+- In particular, if your contribution involves the creation of a new module or an update to an existing module:
+  - Make sure you also reflect your changes in the module `readme.md` file. Refer to the [Generate module Readme](./Contribution%20guide%20-%20Generate%20module%20Readme) section for details on how to leverage the Readme generator utility to support you with this task.
+  - If you are adding or updating role assignments to resources deployable by the module, refer to the [Get formatted RBAC roles](./Contribution%20guide%20-%20Get%20formatted%20RBAC%20roles) section for details on how to leverage the RBAC roles formatting utility to support you with this task.
+  - If applicable, make sure you set or update the major and minor versions in the corresponding module `version.json` file.
+
+# Validate the contribution
+
+Once the contribution is implemented and the changes are pushed to your forked repository, how you proceed depends on the scenario:
+
+- In case you want to contribute to the documentation, you can skip this step.
+
+- In case your contribution involves changes to the library (the modules) and/or to the CI environment (the pipelines), we kindly ask you to validate your updates against your environment before requesting to merge them to the main repo. Test your code leveraging the CARML CI environment, as detailed in the [Pipeline usage](./The%20CI%20environment%20-%20Pipeline%20usage) section.
+
+# Open a PR
+
+Finally, once your contribution is implemented and validated, open a PR for CARML maintainers to review. Make sure you:
+
+- Follow instructions you find in the PR template.
+- Set your Github handle as assignee.
+- Reference the issue number as per the [Create or pick up an issue](#Create-or-pick-up-an-issue) step.
+- If applicable, please reference the badge status of your pipeline run. This badge will show the reviewer that the code changes were successfully validated & tested in your environment. To create a badge, first select the three dots (`...`) to the top right of the pipeline, and further the `Create status badge` option.
+
+    <img src="./media/badgeDropdown.png" alt="Badge dropdown" height="200">
+
+  In the opening pop up, you first need to select your branch and then click on the `Copy status badge Markdown`
+
+    <img src="./media/carmlStatusBadge.png" alt="Status badge" height="400">
+
+

docs/wiki/Contribution guide - Generate module readme.md

@@ -0,0 +1,49 @@
+As per CARML module design structure, every module in the CARML library requires a ReadMe markdown file documenting the set of deployable resource types, input and output parameters and a set of relevant template references from the official Azure Resource Reference documentation.
+
+The ReadMe generator utility aims to simplify contributing to the CARML library, as it supports creating from scratch or updating the module ReadMe markdown file.
+
+---
+
+### _Navigation_
+
+- [Location](#location)
+- [How it works](#what-it-does)
+  - [Special case: 'Parameter Usage' section](#special-case-parameter-usage-section)
+- [How to use it](#how-to-use-it)
+
+---
+# Location
+
+You can find the script under `/utilities/tools/Set-ModuleReadMe.ps1`
+
+# How it works
+
+1. Using the provided template path, the script first makes sure to convert it to ARM/JSON if necessary (i.e. if a path to a Bicep file was provided)
+1. If the intended readMe file does not yet exist in the expected path, it is generated with a skeleton (with e.g. a generated header name)
+1. It then goes through all sections defined as `SectionsToRefresh` (by default all) and refreshes the section content (for example for the `Parameters`) based on the values in the ARM/JSON Template. It detects sections by their header and regenerates always the full section.
+1. Once all are refreshed, the current ReadMe file is overwritten. **Note:** The script can be invoked with a `WhatIf` in combination with `Verbose` to just receive an console-output of the updated content.
+
+## Special case: 'Parameter Usage' section
+
+The `Parameter Usage` examples are located just beneath the `Parameters` table. They are intended to show how to use complex objects/arrays that can be provided as parameters, excluding child-resources as they have their own readMe.
+
+**For the most part, this section is to be populated manually**. However, for a specific set of common parameters, we automatically add their example to the readMe if the parameter exists in the template. At the time of this writing these are:
+- Private Endpoints
+- Role Assignments
+- Tags
+- User Assigned Identities
+
+To be able to change this list with minimum effort, the script reads the content from markdown files in the folder: `utilities/tools/moduleReadMeSource` and matches their title against the parameters of the template file. If a match is found, it's content is added to the readme alongside the generated header. This means, if you want to add another case, you just need to add a new file to the `moduleReadMeSource` folder and follow the naming pattern `resourceUsage-<parameteRName>.md`.
+
+For example, the content of file `resourceUsage-roleAssignments.md` in folder `moduleReadMeSource` is added to a template's readMe if it contains a parameter `roleAssignments`. The combined result is:
+
+```markdown
+### Parameter Usage: `roleAssignments`
+
+<[resourceUsage-roleAssignments.md] file content>
+```
+
+# How to use it
+
+For details on how to use the function please refer to the script's local documentation.
+> **Note:** The script must be loaded before the function can be invoked

docs/wiki/Contribution guide - Get formatted RBAC roles.md

@@ -0,0 +1,91 @@
+Use this script to format a given raw 'Roles' table from Azure to the format required by either Bicep or ARM/JSON Templates in any RBAC deployment.
+
+---
+
+### _Navigation_
+
+- [Location](#location)
+- [How it works](#what-it-does)
+- [How to use it](#how-to-use-it)
+
+---
+# Location
+
+You can find the script under `/utilities/tools/Get-FormattedRBACRoles.ps1`
+
+# How it works
+
+1. From the provided raw and plain roles list, create a list of only the contained role names
+1. Fetch all available roles from Azure
+1. Go through all provided role names, match them with those from Azure to get the matching RoleDefinitionId and format a string like `'<roleName>': subscriptionResourceId('Microsoft.Authorization/roleDefinitions','<roleDefinitionId>')` for each match
+1. Print the result to the terminal
+
+# How to use it
+
+The script does not accept any custom parameter per se, but expects you to replace the placeholder in the `rawRoles` variable inside the script
+
+```PowerShell
+$rawRoles = @'
+    <paste the table here>
+'@
+```
+
+To get the list of roles in the expected format:
+1. Navigate to Azure
+1. Deploy one instance of the service you want to fetch the roles for
+1. Navigate to the `Access Control (IAM)` blade in the resource
+1. Open the `Roles` tab
+1. Set the `Type` in the dropdown to `BuiltInRole`
+
+   <img src="media/rbacRoles.png" alt="Complete deployment flow filtered" height="300">
+
+1. Select and copy the entire table as is to the PowerShell variable.
+
+   The result should look similar to
+
+   ```PowerShell
+   $rawRoles = @'
+   Owner
+   Grants full access to manage all resources, including the ability to assign roles in Azure RBAC.
+   builtInRole
+   General
+   View
+   Contributor
+   Grants full access to manage all resources, but does not allow you to assign roles in Azure RBAC, manage assignments in Azure Blueprints, or share image galleries.
+   BuiltInRole
+   General
+   View
+   Reader
+   View all resources, but does not allow you to make any changes.
+   BuiltInRole
+   General
+   View
+   '@
+   ```
+1. Execute the script. The output for the above example would be
+
+    ```yml
+    VERBOSE: Bicep
+    VERBOSE: -----
+     'Owner':       subscriptionResourceId('Microsoft.Authorization/roleDefinitions','8e3af657-a8ff-443c-a75c-2fe8c4bcb635')
+     'Contributor': subscriptionResourceId('Microsoft.Authorization/roleDefinitions','b24988ac-6180-42a0-ab88-20f7382dd24c')
+     'Reader':      subscriptionResourceId('Microsoft.Authorization/roleDefinitions','acdd72a7-3385-48ef-bd42-f606fba81ae7')
+    VERBOSE:
+    VERBOSE: ARM
+    VERBOSE: ---
+     "Owner":       "[subscriptionResourceId('Microsoft.Authorization/roleDefinitions','8e3af657-a8ff-443c-a75c-2fe8c4bcb635')]",
+     "Contributor": "[subscriptionResourceId('Microsoft.Authorization/roleDefinitions','b24988ac-6180-42a0-ab88-20f7382dd24c')]",
+     "Reader":      "[subscriptionResourceId('Microsoft.Authorization/roleDefinitions','acdd72a7-3385-48ef-bd42-f606fba81ae7')]",
+    ```
+1. Copy the output into the RBAC file into the `buildInRoleNames` variable. Again, for the same example using bicep this would be:
+
+   ```bicep
+   var builtInRoleNames = {
+      'Owner': subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8e3af657-a8ff-443c-a75c-2fe8c4bcb635')
+      'Contributor': subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'b24988ac-6180-42a0-ab88-20f7382dd24c')
+      'Reader': subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'acdd72a7-3385-48ef-bd42-f606fba81ae7')
+   }
+   ```
+
+For further details on how to use the function please refer to the script's local documentation.
+> **Note:** The script must be loaded before the function can be invoked

docs/wiki/Contribution guide.md

@@ -0,0 +1,11 @@
+This section provides the step-by-step process we suggest to follow for contributions to our repository. It also provides details on specific utilities developed to support you with this task.
+
+---
+
+### _Navigation_
+
+- [Contribution flow](./Contribution%20guide%20-%20Contribution%20flow)
+- [Generate module Readme](./Contribution%20guide%20-%20Generate%20module%20Readme)
+- [Get formatted RBAC roles](./Contribution%20guide%20-%20Get%20formatted%20RBAC%20roles)
+
+---

docs/wiki/Home.md

@@ -61,6 +61,7 @@ If you're unfamiliar with Infrastructure as Code, or wonder how you can use the
   - [Bicep to ARM/JSON conversion](./Interoperability%20-%20Bicep%20to%20ARM%20conversion)
   - [Register Azure DevOps pipelines](./Interoperability%20-%20Register%20Azure%20DevOps%20pipelines)
 - [Contribution guide](./Contribution%20guide)
+  - [Contribution flow](./Contribution%20guide%20-%20Contribution%20flow)
   - [Generate module Readme](./Contribution%20guide%20-%20Generate%20module%20Readme)
   - [Get formatted RBAC roles](./Contribution%20guide%20-%20Get%20formatted%20RBAC%20roles)
 - [Known issues](./Known%20issues)