diff --git a/docs/content/contributing/bicep/bicep-contribution-flow/_index.md b/docs/content/contributing/bicep/bicep-contribution-flow/_index.md index 0e18aed15..39a3922b3 100644 --- a/docs/content/contributing/bicep/bicep-contribution-flow/_index.md +++ b/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" %}} + 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" %}} diff --git a/docs/content/help-support/issue-triage/brm-issue-triage.md b/docs/content/help-support/issue-triage/brm-issue-triage.md index 5c4ed53bb..0311bac33 100644 --- a/docs/content/help-support/issue-triage/brm-issue-triage.md +++ b/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  Needs: Core Team 🧞  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: -  Type: Feature Request ➕  -  Type: Bug 🐛  -  Type: Security Bug 🔒  @@ -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 diff --git a/docs/content/help-support/issue-triage/terraform-issue-triage.md b/docs/content/help-support/issue-triage/terraform-issue-triage.md index 09d0030a5..0b8922b5d 100644 --- a/docs/content/help-support/issue-triage/terraform-issue-triage.md +++ b/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  Needs: Core Team 🧞  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: + -  Type: Feature Request ➕  + -  Type: Bug 🐛  + -  Type: Security Bug 🔒  + - For module classification (resource/pattern):  Class: Resource Module 📦  or  Class: Pattern Module 📦  +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  Needs: Triage 🔍  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 diff --git a/docs/content/specs-defs/module-lifecycle.md b/docs/content/specs-defs/module-lifecycle.md index 376c123d0..963ff9ff8 100644 --- a/docs/content/specs-defs/module-lifecycle.md +++ b/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: diff --git a/docs/static/includes/PR-approval-guidance.md b/docs/static/includes/PR-approval-guidance.md new file mode 100644 index 000000000..3c4aa130f --- /dev/null +++ b/docs/static/includes/PR-approval-guidance.md @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + + + +
PR is submitted by a module ownerPR is submitted by anyone, other than the module owner
Module has a single module ownerAVM core team or in case of Terraform only, the owner of another module approves the PRModule owner approves the PR
Module has multiple module ownersAnother owner of the module (other than the submitter) approves the PROne of the owners of the module approves the PR
+