Add AVM GH Labels (#30)

Azure · Aug 31, 2023 · d18aa71 · d18aa71
1 parent e77846b
commit d18aa71
Show file tree

Hide file tree

Showing 14 changed files with 331 additions and 26 deletions.
diff --git a/.github/linters/.markdown-lint.yml b/.github/linters/.markdown-lint.yml
@@ -31,6 +31,7 @@ MD036: false                  # Emphasis used instead of a heading
 MD053: false                  # Super Linter broke this in v4.9.5
 MD024: false                  # Allow multiple headings with same content
 MD037: false                  # Allow spaces inside emphasis markers
+MD046: false                  # Allow hugo styling of codeblocks
 
 #################
 # Rules by tags #

diff --git a/docs/config.toml b/docs/config.toml
@@ -46,7 +46,7 @@ enableRobotsTXT = true
 
   # (Optional, default true) Show a breadcrumb navigation bar at the top of each docs page.
   # You can also specify this parameter per page in front matter.
-  geekdocBreadcrumb = false
+  geekdocBreadcrumb = true
 
   # (Optional, default none) Set source repository location. Used for 'Edit page' links.
   # You can also specify this parameter per page in front matter.

diff --git a/docs/content/_index.md b/docs/content/_index.md
@@ -1,5 +1,5 @@
 ---
-title: Welcome to Azure Verified Modules
+title: Azure Verified Modules
 geekdocNav: true
 geekdocAlign: center
 geekdocAnchor: true

diff --git a/docs/content/faq/_index.md b/docs/content/faq/_index.md
@@ -3,6 +3,7 @@ title: Frequently Asked Questions (FAQs)
 geekdocNav: true
 geekdocAlign: left
 geekdocAnchor: true
+geekdocToC: 1
 ---
 
 {{< hint type=tip >}}
@@ -84,3 +85,7 @@ In these scenarios the AVM modules will not enforce the additional resources to
 Resource modules are written in a flexible way; therefore, you don't need to modify them from project to project, use case to use case, as they aim to cover most of the functionality that a given resource type can provide, in a way that you can interact with any module just by using the required parameters - i.e., you don't have to know how the template of the particular module works inside, just take a look at the `README.md` file of the given module to learn how to leverage it.
 
 Resource modules are multi-purpose; therefore, they contain a lot of dynamic expressions (functions, variables, etc.), so there's no need to maintain multiple instances for different use cases. They can be deployed in different configurations just by changing the input parameters. They should be perceived by the **user** as black boxes, where they don't have to worry about the internal complexity of the code, as they only interact with them by their parameters.
+
+## What is a "Primary Resource" in the context of AVM?
+
+The definition of a Primary Resource is detailed in the [glossary](/Azure-Verified-Modules/glossary/).
diff --git a/docs/content/glossary/_index.md b/docs/content/glossary/_index.md
@@ -11,7 +11,7 @@ This page holds a table of all the terms, abbreviations, and acronyms that are u
 | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | AVM                       | Azure Verified Modules                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | IaC                       | Infrastructure-as-Code                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| CARML                     | Common Azure Resource Modules Library - [`Azure/ResourceModules`](https://github.com/azure/resourcemodules)                                                                                                                                                                                                                                                                                                                               |
+| CARML                     | Common Azure Resource Modules Library - [`Azure/ResourceModules`](https://github.com/azure/resourcemodules)                                                                                                                                                                                                                                                                                                                              |
 | TFVM                      | Terraform Verified Modules - [`Azure/terrafrom-azure-mdoules`](https://github.com/Azure/terraform-azure-modules)                                                                                                                                                                                                                                                                                                                         |
 | FY                        | Microsoft Fiscal Year (July to June)                                                                                                                                                                                                                                                                                                                                                                                                     |
 | CY                        | Calendar Year (January to December)                                                                                                                                                                                                                                                                                                                                                                                                      |
@@ -30,3 +30,4 @@ This page holds a table of all the terms, abbreviations, and acronyms that are u
 | MCSB                      | [Microsoft Cloud Security Benchmark](https://learn.microsoft.com/security/benchmark/azure/introduction)                                                                                                                                                                                                                                                                                                                                  |
 | MCR                       | [Microsoft Container Registry](https://github.com/microsoft/containerregistry). Which is what the Bicep Public Registry uses to publish it's modules via.                                                                                                                                                                                                                                                                                |
 | PR                        | [Pull Request](https://docs.github.com/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)                                                                                                                                                                                                                                                                             |
+| Primary Resource          | A primary resource is the main Azure service/product a Resource Module provides / is built around.                                                                                                                                                                                                                                                                                                                                       |
diff --git a/docs/content/specs/_index.md b/docs/content/specs/_index.md
@@ -7,7 +7,7 @@ geekdocAnchor: true
 
 This section documents all the specifications for Azure Verified Modules (AVM) and their respective IaC languages.
 
-- [Shared](/Azure-Verified-Modules/specs/shared)
+- [Shared (Bicep & Terraform)](/Azure-Verified-Modules/specs/shared)
   - [Interfaces](/Azure-Verified-Modules/specs/shared/interfaces)
 - [Bicep Specific](/Azure-Verified-Modules/specs/bicep)
-- [Terraform Specific](/Azure-Verified-Modules/specs/terraform)
+- [Terraform Specific](/Azure-Verified-Modules/specs/terraform)
diff --git a/docs/content/specs/bicep/_index.md b/docs/content/specs/bicep/_index.md
@@ -19,17 +19,19 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
 
 {{< toc >}}
 
-## Functional Requirements
+## Shared Requirements (Resource & Pattern Modules)
 
-### ID: BCPFR1 - Category: Composition - Cross-Referencing Modules
+### Functional Requirements
+
+#### ID: BCPFR1 - Category: Composition - Cross-Referencing Modules
 
 Module owners **MAY** cross-references other modules to build either Resource or Pattern modules.
 
 However, they **MUST** be referenced only by a public registry reference to a pinned version e.g. `br/public:avm/xxx/yyy:1.2.3`. They **MUST NOT** use local parent path references to a module e.g. `../../xxx/yyy.bicep`.
 
 Although, child modules, that are children of the primary resources being deployed by the AVM Resource Module, **MAY** be specified via local child path e.g. `child/resource.bicep`.
 
-### ID: BCPFR2 - Category: Composition - Role Assignments Role Definition Mapping
+#### ID: BCPFR2 - Category: Composition - Role Assignments Role Definition Mapping
 
 Module owners **MAY** define common RBAC Role Definition names and IDs within a variable to allow consumers to define a RBAC Role Definition by their name rather than their ID, this should be self contained within the module themselves.
 
@@ -46,10 +48,9 @@ Review the [Bicep Contribution Guide's 'RBAC Role Definition Name Mapping' secti
 
 {{< /hint >}}
 
+### Non-Functional Requirements
 
-## Non-Functional Requirements
-
-### ID: BCPNFR1 - Category: Inputs - Data Types
+#### ID: BCPNFR1 - Category: Inputs - Data Types
 
 To simplify the consumption experience for module consumers when interacting with complex data types input parameters, mainly objects and arrays, the Bicep feature of [User-Defined Types](https://learn.microsoft.com/azure/azure-resource-manager/bicep/user-defined-data-types) **MUST** be used and declared.
 
@@ -71,7 +72,7 @@ Therefore it has been decided by the AVM core team that CARML modules initial mi
 
 {{< /hint >}}
 
-### ID: BCPNFR2 - Category: Documentation - Module Documentation Generation
+#### ID: BCPNFR2 - Category: Documentation - Module Documentation Generation
 
 {{< hint type=note >}}
 
@@ -81,7 +82,7 @@ This script/tool is currently being developed by the AVM team and will be made a
 
 Bicep modules documentation **MUST** be automatically generated via the provided script/tooling from the AVM team.
 
-### ID: BCPNFR3 - Category: Documentation - Parameter Files
+#### ID: BCPNFR3 - Category: Documentation - Parameter Files
 
 Bicep modules **MUST** provide parameter files in the following formats:
 
@@ -94,7 +95,7 @@ Bicep Parameter Files (`.bicepparam`) are being reviewed and considered by the A
 
 {{< /hint >}}
 
-### ID: BCPNFR4 - Category: Documentation - Parameter Input Examples
+#### ID: BCPNFR4 - Category: Documentation - Parameter Input Examples
 
 Bicep modules **MUST** provide parameter input examples for each parameter using the `metadata.example` property via the `@metadata()` decorator.
 
@@ -108,7 +109,7 @@ Example:
 param location string = resourceGroup().location
 ```
 
-### ID: BCPNFR5 - Category: Composition - Role Assignments Role Definition Mapping Limits
+#### ID: BCPNFR5 - Category: Composition - Role Assignments Role Definition Mapping Limits
 
 As per [BCPFR2](#id-bcpfr2---category-composition---role-assignments-role-definition-mapping), module owners **MAY** define common RBAC Role Definition names and IDs within a variable to allow consumers to define a RBAC Role Definition by their name rather than their ID.
 
@@ -129,7 +130,7 @@ Review the [Bicep Contribution Guide's 'RBAC Role Definition Name Mapping' secti
 {{< /hint >}}
 
 
-### ID: BCPNFR6 - Category: Composition - Role Assignments Role Definition Mapping Compulsory Roles
+#### ID: BCPNFR6 - Category: Composition - Role Assignments Role Definition Mapping Compulsory Roles
 
 Module owners **MUST** include the following roles in the variable for RBAC Role Definition names:
 

diff --git a/docs/content/specs/shared/_index.md b/docs/content/specs/shared/_index.md
@@ -1,5 +1,5 @@
 ---
-title: Shared Specification
+title: Shared Specification (Bicep & Terraform)
 geekdocNav: true
 geekdocAlign: left
 geekdocAnchor: true
@@ -18,7 +18,8 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
 {{< /hint >}}
 
 {{< toc >}}
-## Shared Requirements
+
+## Shared Requirements (Resource & Pattern Modules)
 
 Listed below are both functional and non-functional requirements for both classifications of AVM modules (Resource and Pattern)
 
@@ -194,6 +195,35 @@ For example, if an AVM Resource Module is used in an AVM Pattern Module that was
 
 This avoids AVM Module owners from having to maintain multiple major release versions.
 
+#### ID: SNFR23 - Category: Contribution/Support - GitHub Repo Labels
+
+GitHub repositories where modules are held **MUST** use the below labels and **SHOULD** not use any additional labels:
+
+{{< expand "AVM Standard GitHub Labels" "expand/collapse" >}}
+
+These labels are available in a CSV file from [here](/Azure-Verified-Modules/governance/avm-standard-github-labels.csv)
+
+{{< entireCsvToTable header=true csv="/static/governance/avm-standard-github-labels.csv" >}}
+
+{{< /expand >}}
+
+To help apply these to a module GitHub repository you can use the below PowerShell script:
+
+{{< expand "Set-AvmGitHubLabels.ps1" "expand/collapse" >}}
+
+For most scenario this is the command you'll need to call the below PowerShell script with, replacing the value for `RepositoryName`:
+
+```powershell
+Set-AvmGitHubLabels.ps1 -RepositoryName "Org/MyGitHubRepo" -CreateCsvLabelExports $false -NoUserPrompts $true
+```
+
+Be aware this script  by default, will remove all pre-existing labels from the repository, but this can be changed by setting the `-RemoveExistingLabels` parameter to `$false`
+
+Full Script:
+
+{{< include file="/static/scripts/Set-AvmGitHubLabels.ps1" language="powershell" options="linenos=false" >}}
+
+{{< /expand >}}
 #### ID: SNFR13 - Category: Forking - Private Module Registry Support
 
 A module **MUST** also function within a private module registry, internal Git repo.

diff --git a/docs/content/specs/shared/module-classifications.md b/docs/content/specs/shared/module-classifications.md
@@ -1,5 +1,5 @@
 ---
-title: Module Classification Definitions
+title: Module Classifications
 geekdocNav: true
 geekdocAlign: left
 geekdocAnchor: true

diff --git a/docs/content/specs/terraform/_index.md b/docs/content/specs/terraform/_index.md
@@ -19,9 +19,11 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
 
 {{< toc >}}
 
-## Functional Requirements
+## Shared Requirements (Resource & Pattern Modules)
 
-### ID: TFFR1 - Category: Composition - Cross-Referencing Modules
+### Functional Requirements
+
+#### ID: TFFR1 - Category: Composition - Cross-Referencing Modules
 
 Module owners **MAY** cross-references other modules to build either Resource or Pattern modules. However, they **MUST** be referenced only by a HashiCorp Terraform registry reference to a pinned version e.g.
 
@@ -48,21 +50,21 @@ module "other-module" {
 
 > See [Module Sources](https://developer.hashicorp.com/terraform/language/modules/sources) for more information
 
-## Non-Functional Requirements
+### Non-Functional Requirements
 
-### ID: TFNFR1 - Category: Documentation - Parameter Input Examples
+#### ID: TFNFR1 - Category: Documentation - Parameter Input Examples
 
 Terraform modules **MUST** provide variable input examples for each variable using the HEREDOC format and embedded markdown.
 
 Example:
 
 {{< include file="/static/includes/sample.var_example.tf" language="terraform" options="linenos=false" >}}
 
-### ID: TFNFR2 - Category: Documentation - Module Documentation Generation
+#### ID: TFNFR2 - Category: Documentation - Module Documentation Generation
 
 Terraform modules documentation **MUST** be automatically generated via [Terraform Docs](https://github.com/terraform-docs/terraform-docs)
 
-### ID: TFNFR3 - Category: Documentation - Module README Layout
+#### ID: TFNFR3 - Category: Documentation - Module README Layout
 
 Terraform modules **MUST** follow the below order for their docs layout for Terraform Docs:
 

diff --git a/docs/data/menu/main.yaml b/docs/data/menu/main.yaml
@@ -23,7 +23,7 @@ main:
       - name: 'Module Specifications'
         ref: 'specs'
         sub:
-          - name: 'Shared'
+          - name: 'Shared (Bicep & Terraform)'
             ref: 'specs/shared'
             sub:
               - name: 'Interfaces'

diff --git a/docs/layouts/shortcodes/entireCsvToTable.html b/docs/layouts/shortcodes/entireCsvToTable.html
@@ -0,0 +1,19 @@
+{{ $useHeaderRow := .Get "header" }}
+{{ $csv := .Get "csv" }}
+{{ $file := readFile $csv }}
+{{ $rows := $file | transform.Unmarshal }}
+
+<table>
+  {{ if $useHeaderRow }}
+    {{ $headerRow := index $rows 0 }}
+    {{ $rows = after 1 $rows }}
+    <thead> <tr> {{ range $headerRow }} <th>{{ . }}</th> {{ end }} </tr> </thead>
+  {{ end }}
+  {{ range $rows }}
+    <tr>
+      {{ range . }}
+        <td>{{ emojify . }}</td>
+      {{ end }}
+    </tr>
+  {{ end }}
+</table>
diff --git a/docs/static/governance/avm-standard-github-labels.csv b/docs/static/governance/avm-standard-github-labels.csv
@@ -0,0 +1,26 @@
+Name,Description,HEX
+Needs: Attention :wave:,"Reply has been added to issue, maintainer to review",E99695
+Needs: Author Feedback :ear:,Awaiting feedback from the issue/PR author,F18A07
+Needs: External Changes :hammer_and_pick:,When an issue/PR requires changes that are outside of the control of the module. e.g. to an RP.,DE389D
+Needs: More Evidence :balance_scale:,We are looking for more evidence to make a decision on this,F64872
+Needs: Triage :mag:,Maintainers need to triage still,FBCA04
+Status: Awaiting Release To Be Cut :scissors:,"This is fixed in the main branch but not in the latest release, will be fixed with next release cut",800080
+Status: Do Not Merge :no_entry:,Do not merge PRs with this label attached as they are not ready or aligned to future direction etc.,8b4513
+Status: External Contribution :earth_africa:,This is being worked on by someone outside of the AVM module owners/contributors or AVM core team,D8FA2C
+Status: Fixed :white_check_mark:,Auto label applied when issue fixed by merged PR,90ee90
+Status: Help Wanted :sos:,Extra attention is needed,ff4500
+Status: In PR :point_right:,This is when an issue is due to be fixed in an open PR,ededed
+Status: Invalid :x:,This doesn't seem right,e4e669
+Status: Long Term :hourglass_flowing_sand:,"We will do it, but will take a longer amount of time due to complexity/priorities",B60205
+Status: No Recent Activity :zzz:,When an issue/PR has not been modified for X amount of days,808080
+Status: Wont Fix :-1:,This will not be worked on,ffffff
+Type: Bug :bug:,Something isn't working,d73a4a
+Type: Documentation :page_facing_up:,Improvements or additions to documentation,0075ca
+Type: Duplicate :palms_up_together:,This issue or pull request already exists,cfd3d7
+Type: Feature Request :heavy_plus_sign:,New feature or request,a2eeef
+Type: Hygiene :broom:,"things related to testing, issue triage etc.",17016A
+Type: New Module Proposal :bulb:,A new module for AVM is being proposed,add8e6
+Type: Question/Feedback :raising_hand:,Further information is requested or just some feedback,CB6BA2
+Type: Security Bug :lock:,This is a security bug,ffff00
+Status: Module Orphaned :eyes:,The module has no owner and is therefore orphaned at this time,f4a460
+Type: AVM :a: :v: :m:,This is an AVM related issue,f0ffff