Enhance PR approval guidance and module lifecycle documentation

docs/content/contributing/bicep/bicep-contribution-flow/_index.md

@@ -36,12 +36,15 @@ flowchart TD
     click E "{{% siteparam base %}}/contributing/bicep/bicep-contribution-flow/#5-createupdate-and-run-tests"
   F(6 - Create a pull request to the upstream repository)
     click F "{{% siteparam base %}}/contributing/bicep/bicep-contribution-flow/#6-create-a-pull-request-to-the-public-bicep-registry"
+  G(7 - Get your pull request approved)
+    click G "{{% siteparam base %}}/contributing/bicep/bicep-contribution-flow/#7-get-your-pull-request-approved"
   A --> B
   B --> C
   C --> D
   D --> E
   E -->|yes|F
   E -->|no|D
+  F --> G
 
 {{< /mermaid >}}
 
@@ -547,6 +550,29 @@ If you're the **sole owner of the module**, the **AVM core team must review and
 
 {{% /notice %}}
 
+## 7. Get your pull request approved
+
+To publish a new module or a new version of an existing module, each Pull Request (PR) **MUST** be reviewed and approved before being merged and published in the Public Bicep Registry. **A contributor (the submitter of the PR) cannot approve their own PR.**
+
+This behavior is assisted by policies, bots, through automatic assignment of the expected reviewer(s) and supporting labels.
+
+{{% notice style="important" %}}
+
+As part of the PR review process, the submitter (contributor) **MUST** address any comments raised by the reviewers and request a new review - and repeat this process until the PR is approved.
+Once the PR is merged, the module owner **MUST** ensure that the related GitHub Actions workflow has successfully published the new version of the module.
+
+{{% /notice %}}
+
+### 7.1. Publishing a new module
+
+When publishing a net new module for the first time ever, the PR **MUST** be reviewed and approved by a member of the core team.
+
+### 7.2. Publishing a new version of an existing module
+
+When publishing a new version of an existing module (i.e., anything that is not being published for the first time ever), the PR approval logic is the following:
+
+{{% include file="/static/includes/PR-approval-guidance.md" %}}
+
 <!--
 ## Publishing to the Registry
 

docs/content/contributing/terraform/terraform-contribution-flow/_index.md

@@ -35,11 +35,14 @@ flowchart TD
     click D "{{% siteparam base %}}/contributing/terraform/terraform-contribution-flow/#4-run-pre-commit-checks"
   E(5 - Create a pull request to the upstream repository)
     click E "{{% siteparam base %}}/contributing/terraform/terraform-contribution-flow/#5-create-a-pull-request-to-the-upstream-repository"
+  F(6 - Get your pull request approved)
+    click F "{{% siteparam base %}}/contributing/terraform/terraform-contribution-flow/#6-get-your-pull-request-approved"
   A --> B
   B --> C
   C --> D
   D -->|yes|E
   D -->|no|C
+  E --> F
 
 {{< /mermaid >}}
 
@@ -278,3 +281,26 @@ These steps are performed by the contributor:
 - `\_header.md` needs to be updated
 - `support.md` needs to be updated
 - Exclude `terraform.tfvars` file from the repository
+
+## 6. Get your pull request approved
+
+To publish a new module or a new version of an existing module, each Pull Request (PR) **MUST** be reviewed and approved before being merged and published in the Terraform Registry. **A contributor (the submitter of the PR) cannot approve their own PR.**
+
+This behavior is assisted by policies, bots, through automatic assignment of the expected reviewer(s) and supporting labels.
+
+{{% notice style="important" %}}
+
+As part of the PR review process, the submitter (contributor) **MUST** address any comments raised by the reviewers and request a new review - and repeat this process until the PR is approved.
+Once the PR is merged, the module owner **MUST** ensure that the related GitHub Actions workflow has successfully published the new version of the module.
+
+{{% /notice %}}
+
+### 6.1. Publishing a new module
+
+When publishing a net new module for the first time ever, the PR **MUST** be reviewed and approved by a member of the core team.
+
+### 6.2. Publishing a new version of an existing module
+
+When publishing a new version of an existing module (i.e., anything that is not being published for the first time ever), the PR approval logic is the following:
+
+{{% include file="/static/includes/PR-approval-guidance.md" %}}

docs/content/help-support/issue-triage/brm-issue-triage.md

@@ -78,7 +78,7 @@ If the issue was opened as a misplaced module proposal, mention the `@Azure/AVM-
     - To indicate that the PR needs the core team's attention, apply the &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#DB4503;color:white;">Needs: Core Team 🧞</mark>&nbsp; label.
 2. If the **PR is submitted by a contributor** (other than the module owner), or the **module is owned by at least 2 people**, **one of the module owners should review and approve the PR**.
 3. Apply relevant labels
-    - Make sure the PR is categorized using one of the following type labels:
+    - Categorize the PR using applicable labels, such as:
       - &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#A2EEEF;">Type: Feature Request ➕</mark>&nbsp;
       - &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#D73A4A;color:white;">Type: Bug 🐛</mark>&nbsp;
       - &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#FFFF00;">Type: Security Bug 🔒</mark>&nbsp;
@@ -94,6 +94,16 @@ If the issue was opened as a misplaced module proposal, mention the `@Azure/AVM-
 
 {{% /notice %}}
 
+{{% notice style="info" title="Who needs to approve the PR?" %}}
+
+The PR approval logic for existing modules is the following:
+
+{{% include file="/static/includes/PR-approval-guidance.md" %}}
+
+This behavior is assisted by bots, through automatic assignment of the expected reviewer(s) and supporting labels.
+
+{{% /notice %}}
+
 ## General Question/Feedback and other standard issues
 
 An issue is considered to be an "AVM Question/Feedback" if

docs/content/help-support/issue-triage/terraform-issue-triage.md

@@ -66,6 +66,27 @@ If the issue was opened as a misplaced module proposal, mention the `@Azure/AVM-
 5. When more detailed plans are available, communicate expected timeline for the update/fix to the requestor (issue author).
 6. Only close the issue, once the next version of the module was fully developed, tested and published.
 
+### Triaging a Module PR
+
+1. If the **PR is submitted by the module owner** and the **module is owned by a single person**, **the AVM core team or the owner of another Terraform module must review and approve the PR**, (as the module owner can't approve their on PR).
+    - To indicate that the PR needs the core team's attention, apply the &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#DB4503;color:white;">Needs: Core Team 🧞</mark>&nbsp; label.
+2. If the **PR is submitted by a contributor** (other than the module owner), or the **module is owned by at least 2 people**, **one of the module owners should review and approve the PR**.
+3. Apply relevant labels
+    - Categorize the PR using applicable labels, such as:
+      - &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#A2EEEF;">Type: Feature Request ➕</mark>&nbsp;
+      - &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#D73A4A;color:white;">Type: Bug 🐛</mark>&nbsp;
+      - &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#FFFF00;">Type: Security Bug 🔒</mark>&nbsp;
+    - For module classification (resource/pattern): &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#D3D3D3;">Class: Resource Module 📦</mark>&nbsp; or &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#A9A9A9;">Class: Pattern Module 📦</mark>&nbsp;
+4. If the module is orphaned (has no owner), make sure the related Orphaned module issue (in the AVM repository) is associated to the PR in a comment, so the new owner can easily identify all related issues and PRs when taking ownership.
+5. Remove the &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#FBCA04;">Needs: Triage 🔍</mark>&nbsp; label.
+
+{{% notice style="important" title="Give your PR a meaningful title" %}}
+
+- **Prefix**: Start with one of the allowed keywords - `fix:` or `feat:` is the most common for module related changes.
+- **Description**: Add a few words, describing the nature of the change.
+
+{{% /notice %}}
+
 ## General Question/Feedback and other standard issues
 
 An issue is considered to be an "AVM Question/Feedback" if

docs/content/specs-defs/module-lifecycle.md

@@ -55,6 +55,22 @@ To **propose a new module**, submit a [module proposal](https://aka.ms/AVM/Modul
 
 Once a module has been fully developed, tested and published in the main branch of the repository and the corresponding public registry (Bicep or Terraform), it is then considered to be "available" and can be used by the community. The module is maintained by the module owner(s). Feature or bug fix requests and related pull requests can be submitted by anyone to the module owner(s) for review.
 
+{{% notice style="info" %}}
+
+To **publish a new version of an existing module** (i.e., anything that is not being published for the first time ever), there's no need to submit any issues in the [AVM repository](https://aka.ms/AVM/repo); contributors can **just submit a Pull Request in the module's repository** with the suggested changes.
+
+{{% expand title="➕ Who needs to approve the PR?" %}}
+
+The PR approval logic for existing modules is the following:
+
+{{% include file="/static/includes/PR-approval-guidance.md" %}}
+
+This behavior is assisted by bots, through automatic assignment of the expected reviewer(s) and supporting labels.
+
+{{% /expand %}}
+
+{{% /notice %}}
+
 ## 3. Orphaned Modules
 
 It is critical to the consumers experience that modules continue to be maintained. In the case where a module owner cannot continue in their role or do not respond to issues as per the defined timescale in the [Module Support page]({{% siteparam base %}}/help-support/module-support/) , the following process will apply:

docs/static/includes/PR-approval-guidance.md

@@ -0,0 +1,19 @@
+<!-- markdownlint-disable -->
+<table>
+  <tr>
+    <td></td>
+    <td align="center"><b>PR is submitted by a module owner</b></td>
+    <td align="center"><b>PR is submitted by anyone, other than the module owner</b></td>
+  </tr>
+  <tr>
+    <td align="center"><b>Module has a <u>single</u> module owner</b></td>
+    <td align="center">AVM core team or in case of Terraform only, the owner of another module approves the PR</td>
+    <td align="center">Module owner approves the PR</td>
+  </tr>
+  <tr>
+    <td align="center"><b>Module has <u>multiple</u> module owners</b></td>
+    <td align="center">Another owner of the module (other than the submitter) approves the PR</td>
+    <td align="center">One of the owners of the module approves the PR</td>
+  </tr>
+</table>
+<!-- markdownlint-restore -->