AVM Issue Triage

This page provides guidance for members of the AVM Core Team on how to triage module proposals and generic issues filed in the AVM repository, as well as how to manage these GitHub issues throughout their lifecycle.

During the AVM Core Team Triage step, the following will be checked, completed and actioned by the AVM Core Team during their triage calls (which are currently twice per week).

Every module needs a module proposal to be created in the AVM repository.

During the triage process, the AVM Core Team should also check the status of following queries:

• Open items that need triaging: Needs: Triage 🔍
  • Bicep items (that need triaging): Language: Bicep 💪 & Needs: Triage 🔍
  • Terraform items (that need triaging): Language: Terraform 🌐 & Needs: Triage 🔍
• Open items that need triaging AND aren’t being triaged yet: Needs: Triage 🔍 & NOT Status: In Triage 🔍
• Open items that need attention: Needs: Attention 👋
• Open items that need owners: Needs: Module Owner 📣
• Open items with no recent activity: Status: No Recent Activity 💤
• Open question/feedback items: Type: Question/Feedback 🙋‍♀️
• Open items with long term status: Status: long-term ⏳
• Open items that are not in a project.

An issue is considered to be a module proposal if

• it was opened through the “New AVM Module Proposal 📝” template,
• it has the labels of “Needs: Triage 🔍” and “Type: New Module Proposal 💡” applied to it, and
• it is assigned to the “AVM - Module Triage” GitHub project.

Follow these steps to triage a module proposal:

1. Add the “Status: In Triage 🔍” label to indicate you’re in the process of triaging the issue.

2. Check module proposal issue/form:

   • Check the Bicep or Terraform module indexes for the proposed module to make sure it is not already available or being worked on.
   • Ensure the module’s details are correct as per specifications - naming, classification (resource/pattern) etc.
   • Check if the module is added to the “Proposed” column on the AVM - Modules Triage GitHub project board.
   • Check if the requestor is a Microsoft FTE.
   • If there’s any additional clarification needed, contact the requestor through comments (using their GH handle) or internal channels - for Microsoft FTEs only! You can look them up by their name or using the Microsoft internal “1ES Open Source Assistant Browser Extension”. Make sure you capture any decisions regarding the module in the comments section.
   • Make adjustments to the module’s name/classification as needed.
   • Change the name of the issue to reflect the module’s name, i.e.,
     • After the “[Module Proposal]:” prefix, change the issues name to the module’s approved name between backticks, i.e., ` and `, e.g., avm/res/sql/managed-instance for a Bicep module, or avm-res-compute-virtualmachine for a Terraform module.
     • Example:
       • “[Module Proposal]: avm/res/sql/managed-instance”
       • “[Module Proposal]: avm-res-sql-managedinstance”
   • Check if the GitHub Policy Service Bot has correctly applied the module language label: “Language: Bicep 💪” or “Language: Terraform 🌐”

3. Apply relevant labels

   • Module classification (resource/pattern): “Class: Resource Module 📦” or “Class: Pattern Module 📦”

As part of the triage of pattern modules, the following points need to be considered/clarified with the module requestor:

• Shouldn’t this be a resource module? What makes it a pattern - e.g., does it deploy multiple resources?
• What is it for? What problem does it fix or provides a solution for?
• What is/isn’t part of it? Which resource and/or pattern modules are planned to be leveraged in it? Provide a list of resources that would be part of the planned module.
• Where is it coming from/what’s backing it - e.g., Azure Architecture Center (AAC), community request, customer example. Provide an architectural diagram and related documentation if possible - or a pointer to these if they are publicly available.
• Don’t let the module’s scope to grow too big, split it up to multiple smaller ones that are more maintainable - e.g., hub & spoke networking should should be split to a generic hub networking and multiple workload specific spoke networking patterns.
• The module’s name should be as descriptive as possible.
• Adopt strict name-to-scope mapping - e.g., hub & spoke networking shouldn’t deploy monitoring.

If requestor is interested in becoming a module owner, but is not a Microsoft FTE, the AVM core team will try to find a Microsoft FTE to be the module owner whom the requestor can collaborate with.

1. If the requestor indicated they didn’t want to or can’t become a module owner (or is not a Microsoft FTE), make sure the “Needs: Module Owner 📣” label is assigned to the issue. Note: the GitHub Policy Service Bot should automatically do this, based on how the issue author responded to the related question.
2. Move the issue to the “Looking for owners” column on the AVM - Modules Triage GitHub project board.
3. Find module owners - if the requestor didn’t volunteer in the module proposal OR the requestor does not want or cannot be owner of the module:
   • Try to find an owner from the AVM communities or await a module owner to comment and propose themselves on the proposal issue.
4. When a new potential owner is identified, continue with the steps described as follows.

If the requestor indicated they want to become the module owner, the GitHub Policy Service Bot will add the “Status: Owners Identified 🤘” label and will assign the issue to the requestor.

You MUST still confirm that the requestor is a Microsoft FTE and that they understand the implications of becoming the owner! If any of these conditions aren’t met, remove the “Status: Owners Identified 🤘” label and unassign the issue from the requestor.

1. Make sure the requestor is a Microsoft FTE. You can look them up by their name or using the Microsoft internal “1ES Open Source Assistant Browser Extension”.
2. Clarify the roles and responsibilities of the module owner:
   • Clarify they understand and accept what “module ownership” means by replying in a comment to the requestor/proposed owner:

<!-- markdownlint-disable -->
Hi @avm_module_owner,

Thanks for requesting/proposing to be an AVM module owner!

We just want to confirm **you agree to the below pages** that define what module ownership means:

- [Team Definitions & RACI](https://azure.github.io/Azure-Verified-Modules/specs/shared/team-definitions)
- [Shared Specification (Bicep & Terraform)](https://azure.github.io/Azure-Verified-Modules/specs/shared)
- [Module Support](https://azure.github.io/Azure-Verified-Modules/help-support/module-support)

Any questions or clarifications needed, let us know!

If you agree, please just **reply to this issue with the exact sentence below** (as this helps with our automation 👍):

"I CONFIRM I WISH TO OWN THIS AVM MODULE AND UNDERSTAND THE REQUIREMENTS AND DEFINITION OF A MODULE OWNER"

Thanks,

The AVM Core Team

#RR
<!-- markdownlint-restore -->

3. Once module owner identified has confirmed they understand and accept their roles and responsibilities as an AVM module owner
   • Make sure the issue is assigned to the confirmed module owner.
   • Move the issue into the “In development” column on the AVM - Modules Triage GitHub Project board.
   • Make sure the “Status: Owners Identified 🤘” label is added to the issue.
     • If applied earlier, remove the “Needs: Module Owner 📣” label from the issue.
   • Remove the labels of “Needs: Triage 🔍” and “Status: In Triage 🔍” to indicate you’re done with triaging the issue.
4. Update the AVM Module Indexes, following the process documented internally.
5. Use the following text to approve module development

<!-- markdownlint-disable -->
Hi @avm_module_owner,

Thanks for confirming that you wish to own this AVM module and understand the related requirements and responsibilities!

Before starting development, please ensure ALL the following requirements are met.

**Please use the following values explicitly as provided in the [module index](https://azure.github.io/Azure-Verified-Modules/indexes/) page**:

- For your module:
  - `ModuleName` - for naming your module
  - `TelemetryIdPrefix` - for your module's [telemetry](https://azure.github.io/Azure-Verified-Modules/specs/shared/#id-sfr3---category-telemetry---deploymentusage-telemetry)
- For your module's repository:
  - Repo name and folder path are defined in `RepoURL`
  - Create GitHub teams for module owners and contributors and grant them permissions as outlined [here](https://azure.github.io/Azure-Verified-Modules/specs/shared/#id-snfr20---category-contributionsupport---github-teams-only).
  - Grant permissions for the AVM core team and PG teams on your GitHub repo as described [here](https://azure.github.io/Azure-Verified-Modules/specs/shared/#id-snfr9---category-contributionsupport---avm--pg-teams-github-repo-permissions).

Check if this module exists in the other IaC language. If so, collaborate with the other owner for consistency. 👍

You can now start the development of this module! ✅ Happy coding! 🎉

**Please respond to this comment and request a review from the AVM core team once your module is ready to be published! Please include a link pointing to your PR, once available. 🙏**

Any further questions or clarifications needed, let us know!

Thanks,

The AVM Core Team
<!-- markdownlint-restore -->

Although, it’s not directly part of the module proposal triage process, to begin development, module owners and contributors might need additional help from the AVM core team, such as:

1. Update any Azure RBAC permissions for test tenants/subscription, if needed.
2. In case of Bicep modules only:
   • Look for the module owners confirmation on the related [Module Proposal] issue that they have created the required -module-owners- and -module-contributors- GitHub teams.
   • Ensure the -module-owners- and -module-contributors- GitHub teams have been assigned to their respective parent teams as outlined here.
   • Ensure the CODEOWNERS file in the BRM repo has been updated.
   • Ensure the AVM Module Issue template file in the BRM repo has been updated.

Once module is developed and v0.1.0 has been published to the relevant registry

1. Assign the “Status: Module Available 🟢” label to the issue.
2. Move the issue into “Done” column in AVM - Modules Triage GitHub Project.
3. Update the AVM Module Indexes, following the process documented internally.
4. Close the issue.

• The Module Proposal issue MUST remain open until the module is fully developed, tested and published to the relevant registry.
• Do NOT close the issue before the successful publication is confirmed!
• Once the module is fully developed, tested and published to the relevant registry, and the Module Proposal issue was closed, it MUST remain closed.

If a module meets the criteria described in the “Orphaned AVM Modules” chapter, the modules is considered to be orphaned and the below steps must be performed.

An issue is considered to be an orphaned module if

• it was opened through the “Orphaned AVM Module 👀” template,
• it has the labels of “Needs: Triage 🔍”, “Needs: Module Owner 📣” and the “Status: Module Orphaned 👀” applied to it, and
• it is assigned to the “AVM - Module Triage” GitHub project.

The original Module Proposal issue related to the module in question MUST remain closed and intact.

Instead, a new Orphaned Module issue must be opened that MUST remain open until the ownership is fully confirmed!

Once the Orphaned Module issue was closed, it MUST remain closed. If the module will subsequently become orphaned again, a new Orphaned Module issue must be opened.

1. Create a new issue using the “Orphaned AVM Module 👀” issue template.
2. Make sure the “Needs: Triage 🔍”, “Needs: Module Owner 📣”, and the “Status: Module Orphaned 👀” labels are assigned to the issue.
3. Move the issue into the “Orphaned” column on the AVM - Modules Triage GitHub Project board.
4. Update the AVM Module Indexes, following the process documented internally.
5. Place an information notice as per the below guidelines:
   • In case of a Bicep module:
     • Place the information notice - with the text below - in an ORPHANED.md file, in the module’s root.
     • Run the avm/utilities/tools/Set-AVMModule.ps1 utility with the module path as an input. This re-generates the module’s README.md file, so that the README.md file will also contain the same notice in its header.
     • Make sure the content of the ORPHANED.md file is displayed in the README.md in its header (right after the title).
   • In case of a Terraform module, place the information notice - with the text below - in the README.md file, in the module’s root.
   • Once the information notice is placed, submit a Pull Request.

Include the following text in the information notice:

⚠️THIS MODULE IS CURRENTLY ORPHANED.⚠️

- Only security and bug fixes are being handled by the AVM core team at present.
- If interested in becoming the module owner of this orphaned module (must be Microsoft FTE), please look for the related "orphaned module" GitHub issue [here](https://aka.ms/AVM/OrphanedModules)!

5. Try to find a new owner using the AVM communities or await a new module owner to comment and propose themselves on the issue.

To look for Orphaned Modules:

• Click on the following link to use this saved query ➡️ Status: Module Orphaned 👀 ⬅️.
• Check the Orphaned swim lane on the Module Triage board.

1. When a new potential owner is identified, clarify the roles and responsibilities of the module owner:
   • Clarify they understand and accept what “module ownership” means by replying in a comment to the requestor/proposed owner:

<!-- markdownlint-disable -->
Hi @avm_module_owner,

Thanks for requesting/proposing to be an AVM module owner!

We just want to confirm **you agree to the below pages** that define what module ownership means:

- [Team Definitions & RACI](https://azure.github.io/Azure-Verified-Modules/specs/shared/team-definitions)
- [Shared Specification (Bicep & Terraform)](https://azure.github.io/Azure-Verified-Modules/specs/shared)
- [Module Support](https://azure.github.io/Azure-Verified-Modules/help-support/module-support)

Any questions or clarifications needed, let us know!

If you agree, please just **reply to this issue with the exact sentence below** (as this helps with our automation 👍):

"I CONFIRM I WISH TO OWN THIS AVM MODULE AND UNDERSTAND THE REQUIREMENTS AND DEFINITION OF A MODULE OWNER"

Thanks,

The AVM Core Team

#RR
<!-- markdownlint-restore -->

2. Once the new module owner candidate has confirmed they understand and accept their roles and responsibilities as an AVM module owner
   • Assign the issue to the confirmed module owner.
   • Remove the “Status: Module Orphaned 👀” and the “Needs: Module Owner 📣” labels from the issue.
   • Add the “Status: Module Available 🟢” and Status: Owners Identified 🤘" labels to the issue.
   • Move the issue into the “Done” column on the AVM - Modules Triage GitHub Project board.
3. Update the AVM Module Indexes, following the process documented internally.
4. Get the new owner(s) and any new contributor(s) added to the related -module-owners- or -module-contributors- teams. See SNFR20 for more details.
5. Remove the information notice (i.e., the file that states that ⚠️THIS MODULE IS CURRENTLY ORPHANED.⚠️, etc. ):
   • In case of a Bicep module:
     • Delete the ORPHANED.md file from the module’s root.
     • Run the avm/utilities/tools/Set-AVMModule.ps1 utility with the module path as an input. This re-generates the module’s README.md file, so that it will no longer contain the orphaned module notice in its header.
     • Double check the previous steps was successful and the README.md file no longer has the information notice in its header (right after the title).
   • In case of a Terraform module, remove the information notice from the README.md file in the module’s root.
   • Once the information notice is removed, submit a Pull Request.
6. Use the following text to confirm the new ownership of an orphaned module:

<!-- markdownlint-disable -->
Hi @avm_module_owner,

Thanks for confirming that you wish to own this AVM module and understand the related requirements and responsibilities!

We just want to ask you to double check a few important things.

**Please use the following values explicitly as provided in the [module index](https://azure.github.io/Azure-Verified-Modules/indexes/) page**:

- You must be the owner of the GitHub teams as outlined [here](https://azure.github.io/Azure-Verified-Modules/specs/shared/#id-snfr20---category-contributionsupport---github-teams-only).
- Please check that your name has been updated in the module index page (this should happen shortly after you confirmed ownership).

You can now take ownership of this module and start improving it as needed! ✅ Happy coding! 🎉

Any further questions or clarifications needed, let us know!

Thanks,

The AVM Core Team
<!-- markdownlint-restore -->

7. Close the Orphaned Module issue.

An issue is a “General Question/Feedback ❔” if it was opened through the “General Question/Feedback ❔” issue template, and has the labels of “Type: Question/Feedback 🙋‍♀️” and “Needs: Triage 🔍” applied to it.

An issue is considered to be a “standard issue” or “blank issue” if it was opened without using an issue template, and hence it does NOT have any labels assigned, OR only has the “Needs: Triage 🔍” label assigned.

When triaging the issue, consider adding one of the following labels as fits:

• Type: Documentation 📄
• Type: Feature Request ➕
• Type: Bug 🐛
• Type: Security Bug 🔒

To see the full list of available labels, please refer to the GitHub Repo Labels section.

If an intended module proposal was mistakenly opened as a “General Question/Feedback ❔” or other standard issue, and hence, it doesn’t have the “Type: New Module Proposal 💡” label associated to it, a new issue MUST be created using the “New AVM Module Proposal 📝” issue template. The mistakenly created “General Question/Feedback ❔” or other standard issue MUST be closed.