AVM Issue Triage
“AVM Core Team Triage” Explained
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).
Note
Every module needs a module proposal to be created in the AVM repository.
Tip
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.
Module Proposal triage
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:
Add the Β Status: In Triage πΒ label to indicate you’re in the process of triaging the issue.
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 Open Source Management Portal’s People finder: “Linked people across Microsoft organizations”. 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-instancefor a Bicep module, oravm-res-compute-virtualmachinefor a Terraform module. - Example:
- “[Module Proposal]:
avm/res/sql/managed-instance” - “[Module Proposal]:
avm-res-sql-managedinstance”
- “[Module Proposal]:
- After the “[Module Proposal]:” prefix, change the issues name to the module’s approved name between backticks, i.e., ` and `, e.g.,
- Check if the GitHub Policy Service Bot has correctly applied the module language label: Β Language: Bicep πͺΒ or Β Language: Terraform πΒ
Apply relevant labels
- Module classification (resource/pattern/utility): Β Class: Resource Module π¦Β , Β Class: Pattern Module π¦Β or Β Class: Utility Module π¦Β
Triaging pattern modules
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.
Scenario 1: Requestor doesn’t want to / can’t be module owner
Note
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.
- 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.
- Move the issue to the “
Looking for owners” column on the AVM - Modules Triage GitHub project board. - Add a comment on the issue with the
#RFRCtag to indicate that the repository should be created. Keep the proposal issue available to the community and potential module owners. - 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.
- When a new potential owner is identified, continue with the steps described as follows.
Scenario 2: Requestor wants to and can become module owner
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.
- Make sure the requestor is a Microsoft FTE. You can look them up by their name or using the Microsoft Open Source Management Portal’s People finder: “Linked people across Microsoft organizations”.
- 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:
- 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. - Add a comment on the issue with the
#RFRCtag to indicate that the repository should be created. - 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.
- Keep the approved name, description, and owners in the proposal issue, then record the supported fields through a metadata pull request. Metadata may be created before the module source exists; the module stays
Proposeduntil it is published. - Use the following text to approve module development
Important
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:
- Update any Azure RBAC permissions for test tenants/subscription, if needed.
- In case of Bicep modules only:
- Confirm that every module owner has approved access through the AVM Module Contributors access package, as outlined in SNFR20. Per-module GitHub teams and parent-team assignments are no longer required. Root
metadata.jsondetermines reviewer notifications; BRM has no per-moduleCODEOWNERSentries.
- Confirm that every module owner has approved access through the AVM Module Contributors access package, as outlined in SNFR20. Per-module GitHub teams and parent-team assignments are no longer required. Root
Post-Development issue management
Once module is developed and v0.1.0 has been published to the relevant registry
- Assign the Β Status: Module Available π’Β label to the issue.
- Move the issue into “
Done” column in AVM - Modules Triage GitHub Project. - Confirm that the module metadata and registry publication are correct. The four-hourly catalog sync then publishes the module index. Submit any metadata corrections to the module repository. For Bicep, verify that module list sync adds the new top-level module to the issue-template dropdown after catalog publication.
- When all development actions are complete and confirmed
In case of Bicep modules - Close the module proposal issue with the following message:
In case of Terraform modules - Close the issue.
Important
- 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.
Changing module owners
There can be several reasons why a module owner change is needed, e.g., the current owner is leaving the company, changing team, or is no longer able to maintain the module. In such cases, the module ownership needs to be transferred to a new owner. While in most cases the module needs to be marked as orphaned until it’s taken over by a new module owner, sometimes, the ownership can be transferred through a “hot swap”, where the current owner directly hands over ownership to another person without the module becoming orphaned first.
Note
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.
Adding or removing co-owners
Agree changes with the current owners and the AVM core team. Confirm each incoming owner’s eligibility, written acceptance of the role, and separate access approval. Submit the agreed handle changes to the owners array in the module’s root metadata.json, following the metadata review process. Use bare handles for individuals and qualified handles for approved existing teams. Keep every continuing individual or team owner; children inherit the root’s ownership.
Use the hot-swap process for a handover. If no owners remain, follow the orphaning process instead.
Orphaned modules
If a module meets the criteria described in the “Orphaned Modules” chapter, the module is considered to be orphaned and the below steps must be performed.
When a module becomes orphaned
- Submit an “orphaned module” issue by using the “Orphaned AVM Module π‘” issue template.
- Make sure the Β Needs: Triage πΒ , Β Needs: Module Owner π£Β , and the Β Status: Module Orphaned π‘Β labels are assigned to the issue and it is assigned to the “AVM - Module Triage” GitHub project.
- Move the issue into the “
Orphaned” column on the AVM - Modules Triage GitHub Project board. - Submit and merge the ownership change in a pull request to the module’s root
metadata.json, linked to the orphaned module issue. Set"owners": [], removing all individual and team handles, following the metadata review process. Do not edit child ownership or set a status field. A published, non-deprecated module with no owners is shown asOrphaned; see how module status is calculated.``` - Replace the label Β Needs: Triage πΒ with the label Β Needs: In TriageπΒ & Add the appropriate label for the class of module i.e. Resoruce/Pattern/Utility
- Try to find a new owner using the AVM communities or await a new module owner to comment and propose themselves on the issue.
For both Bicep and Terraform, the root metadata change is the only module-file change required. No ORPHANED.md file, manual README.md notice, or README regeneration is required. The scheduled catalog sync publishes the new status; do not edit generated indexes or create a module release.
When a new owner is identified
Tip
To look for Orphaned Modules:
- Click on the following link to use this saved query β‘οΈ Β Status: Module Orphaned π‘Β β¬ οΈ.
- Check the
Orphanedswim lane on the Module Triage board.
- When a new potential owner is identified, confirm they are a Microsoft FTE and 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:
- 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.
- Submit a pull request adding the approved incoming handles to the
ownersarray in the module’s rootmetadata.json, linked to the orphaned module issue. Obtain approval from either metadata code-owner team and merge the change through the metadata review process. - Ensure every new owner has approved access through the AVM Module Contributors access package. See SNFR20 for the language-specific access requirements.
- Use the following text to confirm the new ownership of an orphaned module:
- Once the metadata change is reviewed and merged and all access requirements above are complete, close the orphaned module issue with the following message. Closing the issue moves it to “
Done” on the AVM - Modules Triage board. The module index updates automatically at the next four-hourly catalog sync.
Hot swapping module owners
When the module owner needs to be changed without the module becoming orphaned, the overall process described in the Orphaned modules chapter needs to be followed, with a few differences.
- Submit an “orphaned module” issue by using the “Orphaned AVM Module π‘” issue template while indicating the GitHub handle of the new owner.
- Clarify the roles and responsibilities of the module owner by replying in a comment to the requestor/proposed owner:
- Assign the issue to the new module owner.
- Remove these labels:
- Β Needs: Triage πΒ
- Β Needs: Module Owner π£Β
- Β Status: Module Orphaned π‘Β
- Add these labels to the issue:
- Β Status: In Triage πΒ
- Β Status: Module Available π’Β
- Β Status: Owners Identified π€Β labels to the issue.
- Module classification (resource/pattern/utility): Β Class: Resource Module π¦Β , Β Class: Pattern Module π¦Β or Β Class: Utility Module π¦Β
- Make sure the issue is assigned to the “AVM - Module Triage” GitHub project, but don’t move the issue to the “
Orphaned” column of this board as it will be automatically moved to the “Done” column, once the issue is closed. - Once each incoming owner’s eligibility and written consent are confirmed, replace the departing handles with the approved incoming handles in the root
ownersarray in the same metadata change, retaining every continuing individual or team owner. Remove team handles only if they no longer apply. Obtain approval from either metadata code-owner team and merge through the metadata review process. Confirm every incoming owner has approved access as described in SNFR20 before finalizing the handover. - Use the following text to finalize the new ownership transfer:
- Once the metadata change is reviewed and merged and the handover and access requirements above are complete, close the orphaned module issue with the following message. The module index updates automatically at the next four-hourly catalog sync.
Deprecated modules
When a module becomes deprecated
If a module meets the criteria described in the “Deprecated Modules” chapter, the module is considered to be deprecated and the below steps must be performed.
Language agnostic steps
- Submit a “deprecated module” issue by using the “Deprecate AVM Module π΄” issue template.
- Make sure the Β Needs: Triage πΒ and the Β Status: Module Deprecated π΄Β labels are assigned to the issue and it is assigned to the “AVM - Module Triage” GitHub project.
- Record the approved deprecation decision in the issue and complete the language-specific steps below. Do not clear owners to deprecate a module or add a lifecycle/status field to
metadata.json.
Bicep specific steps
- Update the module and connected files as per the below guidelines:
- Place the information notice - with the text below - in an
DEPRECATED.mdfile, in the module’s root. - Run the
utilities/tools/Set-AVMModule.ps1utility with the module path &-SkipBuildswitch as an input. This re-generates the module’sREADME.mdfile, so that theREADME.mdfile will also contain the same notice in its header. For more instructions on how to use the script, please refer to the corresponding section in the Contribution Guide. - Make sure the content of the
DEPRECATED.mdfile is displayed in theREADME.mdin its header (right after the title). - Add the the notice
NOTE: This is the last published version and the module has since been deprecated.to the top-most### Changessection of the module’sCHANGELOG.mdfile - Remove the module workflow from the
workflowsfolder. - Submit a Pull Request
- For the AVM maintainers: Once the PR is merged, run the .Platform - Publish [moduleIndex.json] workflow with the
regenIndexFromBRMflag set. This will de-list the module so that it won’t show up in the VS-Code Bicep extension going forward.
- Place the information notice - with the text below - in an
Deprecating a module does not require editing CODEOWNERS or deleting a GitHub team. BRM has no per-module code-owner entries; /avm/ intentionally has no owners, while metadata.json remains protected by its own code-owner rule.
Terraform specific steps
- Place the information notice - with the text below - in the
README.mdfile, in the module’s root. - Archive the module’s repository on GitHub.
Catalog publication
The catalog derives Deprecated from Bicep’s DEPRECATED.md or Terraform’s repository archived flag. Complete the retirement steps; the four-hourly catalog sync then publishes the change.
A Bicep marker applies to that module and all its descendants. A root marker therefore covers every child; a child marker leaves its parent and siblings unaffected. Terraform archival applies to all module entries in the repository.
A module deprecated before it was ever published to the registry is removed from the indexes rather than listed as Deprecated.
Catalog publication does not perform the required notices, Bicep workflow removal and registry-index update, or Terraform repository archival. After a top-level Bicep deprecation is published, verify that module list sync removes it from the issue-template dropdown instead of editing the list by hand.
Deprecation information notice (to be place in the module’s repository as described above)
General feedback/question, documentation update and other standard issues
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 a “AVM Documentation Update π” if it was opened through the “AVM Documentation Update π” issue template, and has the labels of Β Type: Documentation πΒ 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.
Note
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.