diff --git a/docs/content/contributing/_index.md b/docs/content/contributing/_index.md index 601f9acb2..3fb379684 100644 --- a/docs/content/contributing/_index.md +++ b/docs/content/contributing/_index.md @@ -10,6 +10,7 @@ This section lists all contribution guidance available to module owners and cont - [Process Overview]({{% siteparam base %}}/contributing/process/) - [Bicep Contribution Guide]({{% siteparam base %}}/contributing/bicep/) - [Terraform Contribution Guide]({{% siteparam base %}}/contributing/terraform/) +- [Module Metadata]({{% siteparam base %}}/contributing/module-metadata/) - maintaining module details and ownership - [Contribution Q&A]({{% siteparam base %}}/contributing/q-and-a/) - [Website Contribution Guide]({{% siteparam base %}}/contributing/website/) - [Code of Conduct](https://opensource.microsoft.com/codeofconduct/) diff --git a/docs/content/contributing/bicep/bicep-contribution-flow/child-module-publishing.md b/docs/content/contributing/bicep/bicep-contribution-flow/child-module-publishing.md index 2444cdd38..bf10bf725 100644 --- a/docs/content/contributing/bicep/bicep-contribution-flow/child-module-publishing.md +++ b/docs/content/contributing/bicep/bicep-contribution-flow/child-module-publishing.md @@ -32,7 +32,7 @@ Supporting child module publishing for other module categories, such as pattern Use this section for a fast overview on how to publish a child module. For a step-by-step explanation with detailed instructions, refer to the following sections. -* **Check prerequisites**: Existing [issue in AVM](https://github.com/Azure/Azure-Verified-Modules/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22Class%3A%20Child%20Module%20%3Apackage%3A%22%20label%3A%22Language%3A%20Bicep%20%3Amuscle%3A%22), telemetry ID prefix assigned in [Bicep Module Index CSV](https://github.com/Azure/Azure-Verified-Modules/blob/main/docs/static/module-indexes/BicepResourceModules.csv), module registered in the [MAR file](https://github.com/microsoft/mcr/blob/main/teams/bicep/bicep.yml). +* **Check prerequisites**: Existing [issue in AVM](https://github.com/Azure/Azure-Verified-Modules/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22Class%3A%20Child%20Module%20%3Apackage%3A%22%20label%3A%22Language%3A%20Bicep%20%3Amuscle%3A%22), [assigned telemetry ID prefix](#telemetry-id-prefix-assigned), module registered in the [MAR file](https://github.com/microsoft/mcr/blob/main/teams/bicep/bicep.yml). * Implement required changes in your fork: * **Allowed list**: If not present, add child module to [child-module-publish-allowed-list.json](https://github.com/Azure/bicep-registry-modules/blob/main/utilities/pipelines/staticValidation/compliance/helper/child-module-publish-allowed-list.json). * **Child module template**: Add `enableTelemetry` parameter and `avmTelemetry` deployment to child `main.bicep` template. @@ -67,16 +67,24 @@ If the Bicep Child Module Proposal issue was just created, please allow a few da {{% /notice %}} +Check `telemetryIdPrefix` in the child's own `metadata.json` and keep it consistent with the child module source. Record only the assigned identifier through [metadata review]({{% siteparam base %}}/contributing/module-metadata/). Ownership is inherited from the root. + +You can also look up the assigned prefix in the published index: + 1. Check the online [Bicep resource module index source CSV](https://github.com/Azure/Azure-Verified-Modules/blob/main/docs/static/module-indexes/BicepResourceModules.csv). 1. Search for the child module name in the `ModuleName` field. 1. Verify if the corresponding value exists in the `TelemetryIdPrefix` field. Note down the value as you will need it in the implementation phase. 1. If not found, please reach out to the core team, mentioning the `@Azure/azure-verified-modules-tooling-contributors` via the Bicep Child Module Proposal issue. +If the identifier is missing or conflicts with the index, ask the core team to resolve it. Do not invent an identifier or copy the parent's prefix. + ### Module registered in the MAR-file Ensure that the child module is registered in the [MAR file](https://github.com/microsoft/mcr/blob/main/teams/bicep/bicep.yml). If not, please reach out to the core team, mentioning the `@Azure/azure-verified-modules-tooling-contributors` via the Bicep Child Module Proposal issue. +Metadata approval does not replace MAR registration or approval to publish the child module. + {{% notice style="note" %}} The MAR-file can only be accessed by Microsoft FTEs. If you are missing access, please reach out to the parent module owner for help. diff --git a/docs/content/contributing/bicep/bicep-contribution-flow/owner-contribution-flow.md b/docs/content/contributing/bicep/bicep-contribution-flow/owner-contribution-flow.md index ae379fdf9..c7af6c0a7 100644 --- a/docs/content/contributing/bicep/bicep-contribution-flow/owner-contribution-flow.md +++ b/docs/content/contributing/bicep/bicep-contribution-flow/owner-contribution-flow.md @@ -25,9 +25,9 @@ Familiarize yourself with the responsibilities as **Module Owner** outlined in [ 1. Request and obtain approval for the **[Azure Verified Modules (AVM) Module Contributors access package](https://aka.ms/avm/id/access-package/module-contributor)** as outlined in [SNFR20]({{% siteparam base %}}/spec/SNFR20#bicep). This is required for every primary, secondary, or additional Bicep module owner. Only full-time Microsoft employees can be module owners. - You no longer need to create a per-module GitHub team, assign a parent team, or add the team to `CODEOWNERS`. Access is managed through the shared `@Azure/azure-verified-modules-module-contributors` team. + Access is managed through the shared `@Azure/azure-verified-modules-module-contributors` team. -1. Ensure the [module index]({{% siteparam base %}}/indexes/bicep/) records the correct owners for your module. Coordinate ownership changes with the AVM Core Team. +1. Maintain every approved handle in the `owners` array in your module's root `metadata.json`. Coordinate changes with the AVM Core Team and follow the [metadata review process]({{% siteparam base %}}/contributing/module-metadata/). In BRM, this array also generates your module's `CODEOWNERS` entry, so it controls who is requested for review on your module's pull requests. 1. Ensure your module has been tested before raising a PR. You can do this your own or in another module contributor's environment - if any. Also, once a PR is raised, a GitHub workflow pipeline is required to be run successfully before the PR can be merged. This is to ensure that the module is working as expected and is compliant with the AVM specifications. {{% notice style="note" %}} @@ -42,16 +42,16 @@ If you're the **sole owner of the module**, the **AVM core team must review and Under certain circumstances, you may find yourself unable to continue as the module owner. In such cases, it is advisable to designate a new module owner. The following steps outline this transition: -- Follow the [hot-swapping module owners]({{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#hot-swapping-module-owners) process and wait for the AVM Core Team to confirm the ownership change in the module index. +- Follow the [hot-swapping module owners]({{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#hot-swapping-module-owners) process. Transfer ownership in one root metadata change and wait for approval from either metadata code-owner team and merge before finalizing the handover. - Ensure every incoming owner has approved access through the [Module Contributors access package](https://aka.ms/avm/id/access-package/module-contributor). -No per-module GitHub team membership or `CODEOWNERS` changes are required. Do not remove shared AVM access solely because one module changes owners; it may still be needed for other modules. +Do not remove shared AVM access solely because one module changes owners; it may still be needed for other modules. If a new module owner cannot be identified then the module will need to be "Orphaned". Please follow the step outlined [when-a-module-becomes-orphaned]({{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#when-a-module-becomes-orphaned). ## 3. Adopting an Orphaned Module -When adopting an orphaned module the [when-a-new-owner-is-identified]({{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#when-a-new-owner-is-identified) steps must be followed. +Follow the [adoption process]({{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#when-a-new-owner-is-identified). Add approved owners to the root `metadata.json` through metadata code-owner review and complete the eligibility, consent, access approval, and notice-removal steps. ## 4. GitHub Notification Settings diff --git a/docs/content/contributing/module-metadata.md b/docs/content/contributing/module-metadata.md new file mode 100644 index 000000000..152458ea8 --- /dev/null +++ b/docs/content/contributing/module-metadata.md @@ -0,0 +1,135 @@ +--- +title: Module Metadata +description: Maintaining module metadata and ownership for the Azure Verified Modules (AVM) program +--- + +Maintain a module's details and ownership in `metadata.json` in its source repository. Submit changes through the [review process](#submit-and-review-a-change) below. + +## Find the correct file + +| Language | Root module metadata | +| --- | --- | +| Bicep | `avm/{res,ptn,utl}/{group}/{module}/metadata.json` in [Azure/bicep-registry-modules](https://github.com/Azure/bicep-registry-modules). Use the existing module's actual path. | +| Terraform | `metadata.json` at the root of the module's own repository. Find that repository through the [module indexes]({{% siteparam base %}}/indexes/). | + +Child modules have reduced `metadata.json` files in their own folders. They inherit ownership from the root module, including when nested more than one level deep. **Change owners only in the root file**; child files must not contain `owners`. + +Use the existing file as your starting point and preserve unrelated values. If metadata or an assigned value is missing, ask the AVM core team to confirm the required values. + +## Create metadata.json when scaffolding a new module + +Every new Bicep or Terraform root module, and every new child module or submodule, **MUST** have a valid `metadata.json` created as part of scaffolding, not added later. + +- **Root modules** get the full metadata shape, including the `owners` array. +- **Child modules and submodules** get the reduced, inherited-owner shape described above; they must not contain `owners`. + +Use `Initialize-AvmModuleMetadata` from the [`Avm.Authoring`](https://www.powershellgallery.com/packages/Avm.Authoring) PowerShell module to scaffold the file for either ecosystem. It validates the supplied values against the versioned schema and writes `metadata.json` without overwriting an existing file. You must supply the approved values yourself; the command never infers or backfills them. + +```pwsh +$metadata = @{ + moduleDisplayName = '' + moduleDescription = '' + canonicalType = '' + owners = @('') +} + +Initialize-AvmModuleMetadata -Path . -InputObject $metadata -Ecosystem terraform -ModuleType resource -WhatIf +``` + +`-Ecosystem` (`bicep` or `terraform`) and `-ModuleType` (`resource`, `pattern`, or `utility`) are required. Add `-ChildModule` to scaffold the reduced, owner-less shape for a child module or submodule, omitting `owners` from the input. `-UpdateSource` applies matching Bicep source literals and is not valid for Terraform. Run with `-WhatIf` first to review the plan, then re-run without it to write the file. + +Validate an existing file with `avm metadata validate`, or inspect one with `avm metadata show`. + +Approved modules may carry `metadata.json` before their source exists. The catalog treats a metadata-only module as `Proposed` until it is published. + +## Fields you can maintain + +The versioned schema referenced by the required `$schema` URI defines the supported fields. + +| Field | Guidance | +| --- | --- | +| `$schema` | Keep the required versioned schema URI. It identifies the module metadata schema. | +| `moduleDisplayName`, `moduleDescription` | Maintain the module's curated display name and description. For Bicep, `moduleDescription` must match the `metadata description` literal in `main.bicep`. `moduleDisplayName` is independent of the `metadata name` literal and does not have to match it. | +| `canonicalType` | The real ARM resource type, or the approved pattern/utility taxonomy. [Helper submodules](#helper-submodules) use `helper`. | +| `owners` | Root only: a flat array of strings containing every approved owner. Use bare GitHub handles for individuals and qualified handles such as `@Azure/team-name` for approved existing teams. | +| `telemetryIdPrefix` | Preserve the assigned identifier where required. Do not generate a replacement identifier as part of an ownership or descriptive edit. | +| `alternativeNames`, `comments` | Optional root-module aliases and notes. These are public metadata. | + +Pattern and utility `canonicalType` values can have one or more segments, such as `naming` for `avm-utl-naming`. Preserve the module's approved mapping. Resource modules and non-helper resource children use their actual ARM resource type. + +Module identity and parent relationships come from the repository layout. Changing `moduleDisplayName` does not rename a module or move its repository. + +### Helper submodules + +Helper submodules use the exact `"canonicalType": "helper"` marker with the required `$schema`, `moduleDisplayName`, and `moduleDescription`. Ownership is inherited from the root. Use this marker only for helper children, not root modules or resource children. + +Helper telemetry is optional; any supplied `telemetryIdPrefix` must pass validation. Helpers appear in the JSON catalog, not in the CSV indexes. + +Terraform submodules are excluded from the CSV indexes entirely, not only helpers. Bicep child modules still have their own CSV rows, and the `ParentModule` column names the family root rather than the immediate parent. + +## Submit and review a change + +1. Agree the change with the current owners and the AVM core team. For ownership changes, retain the eligibility checks, incoming owners' written consent, and handover requirements in the [owner-change process]({{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#changing-module-owners). +1. Edit the relevant `metadata.json` on a branch or in your fork of the module repository. Preserve all owners and other values that are not part of the agreed change. +1. Submit a pull request to that repository, linking the proposal or ownership-tracking issue when the process requires one. Describe the intended changes and request review from either [`@Azure/azure-verified-modules-engineering-owners`](https://github.com/orgs/Azure/teams/azure-verified-modules-engineering-owners) or [`@Azure/azure-verified-modules-module-owners`](https://github.com/orgs/Azure/teams/azure-verified-modules-module-owners). +1. Validate metadata using the repository's approved tooling and satisfy its required reviews before merging. Approval from an eligible member of **either** team satisfies metadata code-owner review; approval from both teams is **not** required. Being listed in the module's `owners` array does not by itself authorize someone to approve. Any code changes in the same pull request still need their normal code review and tests. +1. Follow the change through catalog generation and reviewed publication. Do not edit the generated CSV or JSON output to duplicate the metadata change. + +**Metadata-only changes must not trigger a module release.** Do not change version files or create a release just to update owners or other metadata. A Bicep description correction may also require updating the `metadata description` literal in `main.bicep`; that is a source change and must follow normal validation and release rules, not be treated as metadata-only. Display names are independent of source literals and need no source change. + +Merging an owners change in [Azure/bicep-registry-modules](https://github.com/Azure/bicep-registry-modules) also changes review routing. The repository's [`CODEOWNERS` file](https://github.com/Azure/bicep-registry-modules/blob/main/.github/CODEOWNERS) is generated from each root module's `metadata.json`, so every handle in the `owners` array becomes a code owner for that module's path. The generated file ends with a `metadata.json` rule assigned to the two metadata code-owner teams, which is why a metadata change is routed to them rather than to the module's own owners. Do not edit `CODEOWNERS` by hand. + +Editing metadata does not grant or revoke repository permissions, create teams, change identities, or provision Azure access. Every incoming owner still needs the separate access approval described in [SNFR20]({{% siteparam base %}}/spec/SNFR20). Do not remove shared access solely because someone stops owning one module. + +## Ownership changes + +### Add, remove, or transfer owners + +Update the `owners` array in the root metadata file. Add the approved incoming handles and remove only the departing handles. Keep every continuing individual or team owner. + +For a direct transfer, follow [hot swapping module owners]({{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#hot-swapping-module-owners) and make the outgoing and incoming owner changes together, so the module does not pass through an unowned state. Do not reopen a closed module proposal. + +### Orphan a module + +Follow [when a module becomes orphaned]({{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#when-a-module-becomes-orphaned), including its tracking issue and required notices. + +In the root metadata file, set `"owners": []`, removing all individual and team handles from the array. Keep the remaining metadata intact. A published module with no owners is shown as `Orphaned`. See [how module status is calculated](#module-status). + +### Adopt an orphaned module + +Follow [when a new owner is identified]({{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#when-a-new-owner-is-identified). After eligibility and consent are confirmed, add the approved incoming handles to the root metadata's `owners` array and obtain approval from either metadata code-owner team. + +Complete the separate access approval and notice-removal steps before closing the ownership issue. Adding owners does not revive a deprecated module. + +## Catalog updates + +The catalog sync runs on a four-hourly schedule (01:33, 05:33, 09:33, 13:33, 17:33, and 21:33 UTC). Each scheduled run collects metadata from the module repositories, regenerates the six CSV indexes and `v1/modules.json`, and publishes them to the [module indexes and CSV downloads]({{% siteparam base %}}/indexes/) automatically. A merged metadata change therefore appears in the published index within about four hours, without a separate request to the AVM core team. + +The generated outputs are not the source of truth. Propose corrections in the module's `metadata.json` rather than editing generated CSV or JSON files; the next scheduled run overwrites them. The AVM core team owns the [catalog tooling](https://github.com/Azure/azure-verified-modules-tools/tree/main/repository-management/module-catalog) and handles any run that is held back by a safeguard. + +CSV owner columns show the first two individuals. Root metadata and the JSON catalog contain the full owner list. + +### Module status + +The catalog calculates `ModuleStatus` from evidence, not from an authored field. The first matching condition wins: + +| Condition | Status | +| --- | --- | +| Deprecation evidence, or an existing `Deprecated` status in the CSV | `Deprecated` | +| Not published in the registry | `Proposed` | +| Published with no owners | `Orphaned` | +| Published with at least one owner | `Available` | + +A module that is both deprecated and unpublished is omitted from the CSV indexes and `v1/modules.json` altogether, and the run warns that its unused source or repository can be deleted. + +## Related processes + +**New proposals:** Follow the [module proposal and approval process]({{% siteparam base %}}/contributing/process/#new-module-proposal--creation). The approved name, description, and owners are agreed in the proposal issue. Once approved, `metadata.json` may be created before the module source exists; the module stays `Proposed` until it is published. Do not create metadata for a module that has not been approved. + +**Publication:** Registry publication is required before a module is available. A metadata change does not publish a module. + +**Deprecation:** Follow the [deprecation process]({{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#when-a-module-becomes-deprecated), including approval, notices, and language-specific retirement steps. The catalog derives deprecation from Bicep's `DEPRECATED.md` or the Terraform repository's `archived` flag, not an authored metadata status. + +A Bicep marker applies to its module and descendants, not its parent or siblings. Terraform archival applies to every module entry in that repository. Changing owners does not deprecate or reactivate a module. A module that is deprecated before it was ever published is removed from the indexes rather than listed as `Deprecated`. + +**Bicep child publishing:** [Telemetry assignment and Microsoft Artifact Registry (MAR) approval]({{% siteparam base %}}/contributing/bicep/bicep-contribution-flow/child-module-publishing/#prerequisites) remain required. Recording metadata does not grant permission to publish a child module. diff --git a/docs/content/contributing/process.md b/docs/content/contributing/process.md index dd73b211f..8f3a30f5a 100644 --- a/docs/content/contributing/process.md +++ b/docs/content/contributing/process.md @@ -11,6 +11,10 @@ This page provides an overview of the contribution process for AVM modules. Each AVM module **MUST** have a [Module Proposal](https://aka.ms/AVM/ModuleProposal) issue created and approved by the AVM core team before it can be created/migrated! {{% /notice %}} +{{% notice style="note" %}} +Record approved details in the proposal issue. Once the module is approved, maintain those details in its `metadata.json` through the [metadata review process]({{% siteparam base %}}/contributing/module-metadata/). Metadata may be created before the module source exists. +{{% /notice %}} +
@@ -34,22 +38,24 @@ flowchart TD IndexExistenceCheck -->|No|A IndexExistenceCheck -->|Yes|EndExistenceCheck(Review existing/proposed AVM module) EndExistenceCheck -->OrphanedCheck{ Is the module
orphaned? } - click OrphanedCheck "{{% siteparam base %}}/specs/shared/module-lifecycle/#orphaned-avm-modules" + click OrphanedCheck "{{% siteparam base %}}/specs/shared/module-lifecycle/#3-orphaned-modules" OrphanedCheck -->|No|ContactOwner[Contact module owner,
via GitHub issues on the related
repo, to discuss enhancements/
bugs/opportunities to contribute etc.] OrphanedCheck -->|Yes|OrphanOwnerYes(Locate the related issue
and comment on:
- A feature/enhancement suggestion
- Indicating you wish to become the owner) - click OrphanOwnerYes "{{% siteparam base %}}/specs/shared/module-lifecycle/#orphaned-avm-modules" + click OrphanOwnerYes "{{% siteparam base %}}/specs/shared/module-lifecycle/#3-orphaned-modules" OrphanOwnerYes -->B A[[ Create Module Proposal ]] -->|GitHub Issue/Form Submitted| B{ AVM Core Team
Triage } click A "https://aka.ms/avm/moduleproposal" click B "{{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#avm-core-team-triage-explained" B -->|Module Approved for Creation| C[["Module Owner(s) Identified & assigned to GitHub issue/proposal" ]] B -->|Module Rejected| D(Issue closed with reasoning) - C -->E[[ Module index CSV files updated by AVM Core Team]] - click E "{{% siteparam base %}}/indexes/" + C -->E[[ Approved proposal recorded by AVM Core Team]] + click E "{{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#module-proposal-triage" E -->E1[[Repo/Directory Created following the
Contribution Guide ]] click E1 "{{% siteparam base %}}/contributing/" E1 -->F("Module Developed by Owner(s) & their Contributors") - F -->G[[ Module & AVM Compliance Tests ]] + F -->E2[[ Module metadata submitted and reviewed ]] + click E2 "{{% siteparam base %}}/contributing/module-metadata/" + E2 -->G[[ Module & AVM Compliance Tests ]] click G "{{% siteparam base %}}/spec/SNFR3" G -->|Tests Fail|I(Modules/Tests Fixed
To Make Them Pass) I -->F diff --git a/docs/content/contributing/q-and-a.md b/docs/content/contributing/q-and-a.md index 482474810..563e837bc 100644 --- a/docs/content/contributing/q-and-a.md +++ b/docs/content/contributing/q-and-a.md @@ -88,9 +88,13 @@ Beside of providing program level governance, the [AVM core team]({{% siteparam The AVM core team will then triage the request and get back to you with next steps. You can accelerate the process of creating the module by volunteering to be a [module owner]({{% siteparam base %}}/specs/shared/team-definitions/#module-owners). - +Submit module details and ownership changes to the module repository's `metadata.json` through the [metadata review process]({{% siteparam base %}}/contributing/module-metadata/). Ownership is maintained in the root file and requires approval from either metadata code-owner team. + +A catalog sync then regenerates the indexes and publishes them automatically every four hours, so a merged metadata change normally appears in the published index within about four hours. + +For deprecation, follow the [retirement process]({{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#when-a-module-becomes-deprecated). The catalog derives `Deprecated` from Bicep's `DEPRECATED.md` or Terraform's repository `archived` flag. ## Developing a module @@ -186,7 +190,7 @@ You should use GitHub issues to propose changes or improvements for specific mod ### I am using module without owner. What will happened if I need update? -[AVM core team]({{% siteparam base %}}/specs/shared/team-definitions/#avm-core-team) will work to assign owner for every module, but it can happen during a time that there are modules without owner. If you would like to own that module, feel free to ask to take ownership. At this moment, only Microsoft FTEs can be module owners. +[AVM core team]({{% siteparam base %}}/specs/shared/team-definitions/#avm-core-team) will work to assign owner for every module, but it can happen during a time that there are modules without owner. To volunteer, comment on the module's [orphaned module issue](https://aka.ms/AVM/OrphanedModules) and follow the [adoption process]({{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#when-a-new-owner-is-identified). At this moment, only Microsoft FTEs can be module owners. Add approved owners through a pull request to the root metadata file and complete access approval separately. --- diff --git a/docs/content/contributing/terraform/_index.md b/docs/content/contributing/terraform/_index.md index 81fabb647..4878c6da0 100644 --- a/docs/content/contributing/terraform/_index.md +++ b/docs/content/contributing/terraform/_index.md @@ -19,6 +19,7 @@ This section lists AVM's Terraform-specific contribution guidance. - [Prerequisites]({{% siteparam base %}}/contributing/terraform/prerequisites/) — tooling and access requirements - [Contribution Flow]({{% siteparam base %}}/contributing/terraform/contribution-flow/) — end-to-end guide for owners and contributors (includes testing) +- [Module Metadata]({{% siteparam base %}}/contributing/module-metadata/) - maintaining module details and ownership - [Composition]({{% siteparam base %}}/contributing/terraform/composition/) — module structure, code styling, interfaces - [Review]({{% siteparam base %}}/contributing/terraform/review/) — module review process before publishing - [Advanced Topics & FAQ]({{% siteparam base %}}/contributing/terraform/advanced/) — custom subscriptions, OPA exceptions, TFLint overrides diff --git a/docs/content/contributing/terraform/advanced.md b/docs/content/contributing/terraform/advanced.md index c61f2cc07..7f58f8e8f 100644 --- a/docs/content/contributing/terraform/advanced.md +++ b/docs/content/contributing/terraform/advanced.md @@ -161,7 +161,9 @@ Shell equivalents are rejected. Each PowerShell hook runs in an isolated process [Repository sync](https://github.com/Azure/azure-verified-modules-tools/tree/main/repository-management/repository-sync) regularly compares each module repository with the shared [managed files](https://github.com/Azure/azure-verified-modules-managed-files) and opens a PR when updates are available. These PRs are normally merged automatically. Module owners will be informed about one-off PRs that require intervention. -These PRs do not change module code, so no new release is needed. +Sync uses the default branch's root `metadata.json` for the display name and full owner list. Submit changes to those values through the [metadata review process]({{% siteparam base %}}/contributing/module-metadata/#submit-and-review-a-change). + +A synchronization update can include module source and managed configuration. Review any requested intervention accordingly; source changes need normal validation and release handling. A metadata-only change does not require a module release. --- diff --git a/docs/content/contributing/terraform/contribution-flow.md b/docs/content/contributing/terraform/contribution-flow.md index cd00374df..c30270f7d 100644 --- a/docs/content/contributing/terraform/contribution-flow.md +++ b/docs/content/contributing/terraform/contribution-flow.md @@ -392,6 +392,7 @@ For a brand new module being published for the first time, get the module review ### Owner responsibilities +- Keep the root `metadata.json` up to date, including every approved owner, through the [metadata review process]({{% siteparam base %}}/contributing/module-metadata/). Complete owner access approval separately. - Watch PR and issue activity for your module and respond in a timely manner as per [SNFR11]({{% siteparam base %}}/spec/SNFR11). - Familiarize yourself with [Team Definitions & RACI]({{% siteparam base %}}/specs/shared/team-definitions/#module-owners) and [TF Issue Triage]({{% siteparam base %}}/help-support/issue-triage/). @@ -404,7 +405,7 @@ For a brand new module being published for the first time, get the module review ## 9. Cut a release {{% notice style="note" %}} -This step is performed by the **module owner** only. +This step is performed by the **module owner** only. Skip it for metadata-only changes: updates to `metadata.json` must not trigger a module release. See the [metadata maintenance process]({{% siteparam base %}}/contributing/module-metadata/). {{% /notice %}} After the PR is merged to `main`, create a release via [GitHub Releases](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository): diff --git a/docs/content/contributing/terraform/repository-setup.md b/docs/content/contributing/terraform/repository-setup.md index fe01e07e7..e5f274875 100644 --- a/docs/content/contributing/terraform/repository-setup.md +++ b/docs/content/contributing/terraform/repository-setup.md @@ -31,19 +31,21 @@ Until your access request is approved, you can contribute by using JIT elevation ## 2. Gather repository information -You'll need the following from the module request issue: +Gather the following approved values from the module request issue. Repository creation uses them to initialize the root `metadata.json`. | Information | Description | | --- | --- | | Module name | Format: `avm--` (e.g. `avm-res-network-virtualnetwork`) | -| Module owner GitHub handle | Your GitHub handle | -| Module owner display name | `Firstname Lastname` | -| Module description | Auto-prefixed with `Terraform Azure Verified Module for ...` | -| Resource provider namespace | Resource modules only (e.g. `Microsoft.Network`) | -| Resource type | Resource modules only (e.g. `virtualNetworks`) | -| Alternative names | Optional comma-separated list | -| Secondary owner handle | Optional | -| Secondary owner display name | Optional | +| Module provider | Optional `moduleProvider`; defaults to `azure` | +| Module display name | Approved display name, passed as `moduleDisplayName` | +| Module description | Required approved description, passed as `moduleDescription` | +| Canonical type | Required approved ARM resource type or pattern/utility taxonomy, passed as `canonicalType`. Resource modules can instead supply both fields in the next row. Do not infer the value from the module name. | +| Resource provider namespace and resource type | For resource modules only, `resourceProviderNamespace` and `resourceType` together are an alternative to `canonicalType` (e.g. `Microsoft.Network` and `virtualNetworks`). They are not required when `canonicalType` is supplied. | +| Telemetry ID prefix | Optional `telemetryIdPrefix`. Supply the assigned identifier if the proposal has one. If you omit it, creation mints one in the fleet format `46d3xtrf..<7 lowercase hex characters>` for resource and pattern modules. Never hand-pick an identifier yourself. | +| Owners | `ownerGitHubHandles`, a PowerShell string array of approved bare usernames or qualified `@organization/team-slug` entries. `ownerTeam` adds an approved owning team, and the legacy `ownerPrimaryGitHubHandle` and `ownerSecondaryGitHubHandle` parameters are still accepted. | +| Alternative names | Optional `moduleAlternativeNames`, a comma-separated string; the tooling splits it for JSON metadata | + +Record every approved owner. An empty owner array is valid for an unowned module, subject to the proposal and ownership processes. Metadata does not grant access. Later ownership changes use the [metadata review process]({{% siteparam base %}}/contributing/module-metadata/#submit-and-review-a-change). ## 3. Create the repository @@ -51,15 +53,17 @@ Prerequisites: - [PowerShell 7.4 or later](https://learn.microsoft.com/powershell/scripting/install/installing-powershell) - [Git](https://git-scm.com/downloads) - [GitHub CLI](https://cli.github.com) +- AVM core team approval and permission to create the repository, push its contents, and edit its custom properties. +- A configured Git commit identity. ### Clone and prepare -Use the [repository creation tooling](https://github.com/Azure/azure-verified-modules-tools/tree/main/repository-management/repository-creation): +Use a trusted checkout of the [repository creation tooling](https://github.com/Azure/azure-verified-modules-tools/tree/main/repository-management/repository-creation). Its README covers operator prerequisites, additional options, and recovery. ```pwsh -cd ~ +Set-Location $HOME git clone "https://github.com/Azure/azure-verified-modules-tools" -cd ./azure-verified-modules-tools/repository-management/repository-creation +Set-Location .\azure-verified-modules-tools\repository-management\repository-creation ``` ### Authenticate @@ -70,37 +74,31 @@ gh auth login -h "github.com" -w -p "https" ### Run the creation script +Supply the approved `canonicalType` below. For a resource module, you can instead replace that entry with both `resourceProviderNamespace` and `resourceType`; pattern and utility modules require an explicit `canonicalType`. Supply the assigned telemetry prefix if the proposal has one; otherwise omit `telemetryIdPrefix` and let creation mint it for resource and pattern modules. Utility modules do not use telemetry. Do not derive telemetry identifiers from repository names or replace existing identifiers. + ```pwsh -if(!(Test-Path -Path "./scripts/New-Repository.ps1")) { +if (!(Test-Path -Path ".\scripts\New-Repository.ps1")) { Write-Error "This script must be run from the repository-creation directory." exit 1 } -# Required Inputs -$moduleName = "" # e.g. avm-res-network-virtualnetwork -$moduleDisplayName = "" -$resourceProviderNamespace = "" # Leave empty for Pattern/Utility modules -$resourceType = "" # Leave empty for Pattern/Utility modules -$ownerPrimaryGitHubHandle = "" -$ownerPrimaryDisplayName = "" - -# Optional -$moduleAlternativeNames = "" -$ownerSecondaryGitHubHandle = "" -$ownerSecondaryDisplayName = "" - -./scripts/New-Repository.ps1 ` - -moduleName $moduleName ` - -moduleDisplayName $moduleDisplayName ` - -resourceProviderNamespace $resourceProviderNamespace ` - -resourceType $resourceType ` - -ownerPrimaryGitHubHandle $ownerPrimaryGitHubHandle ` - -ownerPrimaryDisplayName $ownerPrimaryDisplayName ` - -moduleAlternativeNames $moduleAlternativeNames ` - -ownerSecondaryGitHubHandle $ownerSecondaryGitHubHandle ` - -ownerSecondaryDisplayName $ownerSecondaryDisplayName +$parameters = @{ + moduleName = "" + moduleDisplayName = "" + moduleDescription = "" + canonicalType = "" + ownerGitHubHandles = @("") +} + +.\scripts\New-Repository.ps1 @parameters -planOnly ``` +Add optional entries from the table when needed, including `telemetryIdPrefix` when the proposal already assigns one. Keep `ownerGitHubHandles` as an array, such as `@("first-owner", "@Azure/approved-team")`, and `moduleAlternativeNames` as a comma-separated string. + +`-planOnly` and `-WhatIf` validate the inputs and show the plan without making GitHub or filesystem changes. Review the plan, including any minted telemetry identifier, and obtain the required approval before running the same command without either switch. + +Creation publishes validated root metadata in the first commit to `main`. If creation fails, stop and follow the recovery guidance in the tooling README before retrying. + ### Complete Open Source Portal Setup The script will pause and prompt you to configure the Open Source Portal. Follow the link in the script output. @@ -145,9 +143,11 @@ Click **Finish setup + start business review**, then **View repository**, then * Return to the terminal and type `yes` to complete repository configuration. -The script will automatically: -- Create a PR to add module metadata to the [`repository-sync` configuration](https://github.com/Azure/azure-verified-modules-tools/tree/main/repository-management/repository-sync). -- Create a PR to install the `Azure Verified Modules` GitHub App. +The script creates the `Azure Verified Modules` GitHub App installation request. + +{{% notice style="note" %}} +Maintain the module's details and full `owners` array through [metadata code-owner review]({{% siteparam base %}}/contributing/module-metadata/#submit-and-review-a-change). Complete the Open Source Portal, access-package, and JIT requirements separately. +{{% /notice %}} ## 4. Upgrade just-in-time access to JITv2 @@ -190,3 +190,5 @@ Module owners retain day-to-day access through the `azure-verified-modules-modul ## 5. Wait for the GitHub App and repository sync After the app is installed, [repository sync](https://github.com/Azure/azure-verified-modules-tools/tree/main/repository-management/repository-sync) applies the shared repository configuration and [managed files](https://github.com/Azure/azure-verified-modules-managed-files) to complete the setup. + +Sync reads the root `metadata.json` from the module repository's default branch for the display name and full owner list. diff --git a/docs/content/contributing/terraform/review.md b/docs/content/contributing/terraform/review.md index 2ce5b8f4f..ad9cf28e0 100644 --- a/docs/content/contributing/terraform/review.md +++ b/docs/content/contributing/terraform/review.md @@ -81,4 +81,5 @@ GitHub Repo Link: " 13. Once the module owner perform the requested action in the previous step, the module reviewer updates the module proposal by performing the following steps: - Assign label Status: Module Available :green_circle: to the module proposal. -- Update the module index excel file and CSV file by creating a PR to update the module index and links the module proposal as an issue that gets closed once the PR is merged which will move the module proposal from "In Review" to "Done" in the [AVM - Module Triage](https://github.com/orgs/Azure/projects/529) project. +- Verify the module's root `metadata.json`, including all approved owners. Correct metadata through a pull request to the module repository using the [metadata review process]({{% siteparam base %}}/contributing/module-metadata/). +- Confirm publication to the Terraform Registry. The four-hourly [catalog sync]({{% siteparam base %}}/contributing/module-metadata/#catalog-updates) publishes the module index automatically once the module is published and its metadata is correct. Close the module proposal after the index shows the module as `Available`, which moves it from "In Review" to "Done" in the [AVM - Module Triage](https://github.com/orgs/Azure/projects/529) project. diff --git a/docs/content/help-support/issue-triage/avm-issue-triage.md b/docs/content/help-support/issue-triage/avm-issue-triage.md index 4fc4f2f26..af59d3f16 100644 --- a/docs/content/help-support/issue-triage/avm-issue-triage.md +++ b/docs/content/help-support/issue-triage/avm-issue-triage.md @@ -77,7 +77,7 @@ If requestor is interested in becoming a module owner, but is not a Microsoft FT 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. 1. Move the issue to the "`Looking for owners`" column on the [AVM - Modules Triage](https://aka.ms/avm/moduletriage) GitHub project board. -1. Add a comment on the issue with the `#RFRC` tag to indicate that the repository should be created. This allows the module to be added the module indexes in the `Proposed` state, so that it can be found by the community and potential module owners. +1. Add a comment on the issue with the `#RFRC` tag to indicate that the repository should be created. Keep the proposal issue available to the community and potential module owners. 1. 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. 1. When a new potential owner is identified, continue with the steps described [as follows](#scenario-2-requestor-wants-to-and-can-become-module-owner). @@ -105,11 +105,11 @@ You **MUST** still confirm that the requestor is a Microsoft FTE and that they u 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](https://aka.ms/avm/moduletriage) GitHub Project board. - - Add a comment on the issue with the `#RFRC` tag to indicate that the repository should be created. This allows the module to be added the module indexes in the `Proposed` state, so that it can be found by the community. + - Add a comment on the issue with the `#RFRC` tag 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. -4. Update the AVM Module Indexes, following the [process documented internally](https://eng.ms/docs/azure-verified-modules-avm/how-to/avm/avm-governance/module-index-update-process.html). +1. Keep the approved name, description, and owners in the proposal issue, then record the supported fields through a [metadata pull request]({{% siteparam base %}}/contributing/module-metadata/). Metadata may be created before the module source exists; the module stays `Proposed` until it is published. 5. Use the following text to approve module development {{% expand title="➕ Final Confirmation for Proposed Module Owners - Bicep" %}} @@ -138,7 +138,7 @@ Although, it's not directly part of the module proposal triage process, to begin 1. Update any Azure RBAC permissions for test tenants/subscription, if needed. 2. In case of **Bicep modules** only: - - Confirm that every module owner has approved access through the [AVM Module Contributors access package](https://aka.ms/avm/id/access-package/module-contributor), as outlined in [SNFR20]({{% siteparam base %}}/spec/SNFR20#bicep). Per-module GitHub teams, parent-team assignments, and `CODEOWNERS` entries are no longer required. + - Confirm that every module owner has approved access through the [AVM Module Contributors access package](https://aka.ms/avm/id/access-package/module-contributor), as outlined in [SNFR20]({{% siteparam base %}}/spec/SNFR20#bicep). Per-module GitHub teams and parent-team assignments are no longer required. `CODEOWNERS` entries are generated from the module's root `metadata.json` and **MUST NOT** be hand-authored. - Ensure the [`AVM Module Issue template`](https://github.com/Azure/bicep-registry-modules/blob/main/.github/ISSUE_TEMPLATE/avm_module_issue.yml) file in the [BRM repo](https://aka.ms/BRM) has been updated. {{% /notice %}} @@ -149,7 +149,7 @@ Once module is developed and `v0.1.0` has been published to the relevant registr 1. Assign the  Status: Module Available 🟢  label to the issue. 2. Move the issue into "`Done`" column in [AVM - Modules Triage](https://aka.ms/avm/moduletriage) GitHub Project. -3. Update the AVM Module Indexes, following the [process documented internally](https://dev.azure.com/CSUSolEng/Azure%20Verified%20Modules/_wiki/wikis/AVM%20Internal%20Wiki/684/Module-index-update-process). +1. Confirm that the module metadata and registry publication are correct. The four-hourly [catalog sync]({{% siteparam base %}}/contributing/module-metadata/#catalog-updates) then publishes the module index. Submit any metadata corrections to the module repository. 4. When all development actions are complete and confirmed 1. **In case of Bicep modules** - Close the module proposal issue with the following message: @@ -185,16 +185,22 @@ Instead, a **new Orphaned Module issue** must be opened that **MUST remain open* 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. {{% /notice %}} +### 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]({{% siteparam base %}}/spec/SNFR20). Submit the agreed handle changes to the `owners` array in the module's **root** `metadata.json`, following the [metadata review process]({{% siteparam base %}}/contributing/module-metadata/#submit-and-review-a-change). 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](#hot-swapping-module-owners) for a handover. If no owners remain, follow the [orphaning process](#when-a-module-becomes-orphaned) instead. + ### Orphaned modules -If a module meets the criteria described in the "[Orphaned Modules]({{% siteparam base %}}/specs/shared/module-lifecycle/#3-orphaned-avm-modules)" chapter, the module is considered to be orphaned and the below steps must be performed. +If a module meets the criteria described in the "[Orphaned Modules]({{% siteparam base %}}/specs/shared/module-lifecycle/#3-orphaned-modules)" chapter, the module is considered to be orphaned and the below steps must be performed. #### When a module becomes orphaned 1. Submit an "orphaned module" issue by using the "[Orphaned AVM Module 🟡](https://aka.ms/AVM/OrphanedModule)" issue template. 2. 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](https://github.com/orgs/Azure/projects/529)" GitHub project. 3. Move the issue into the "`Orphaned`" column on the [AVM - Modules Triage](https://aka.ms/avm/moduletriage) GitHub Project board. -4. Update the AVM Module Indexes, following the [process documented internally](https://dev.azure.com/CSUSolEng/Azure%20Verified%20Modules/_wiki/wikis/AVM%20Internal%20Wiki/684/Module-index-update-process). +1. Include 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]({{% siteparam base %}}/contributing/module-metadata/#orphan-a-module). Do not edit child ownership or set a status field. A published module with no owners is shown as `Orphaned`; see [how module status is calculated]({{% siteparam base %}}/contributing/module-metadata/#module-status). 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. @@ -226,7 +232,7 @@ To look for Orphaned Modules: - Check the `Orphaned` swim lane on the [Module Triage board](https://aka.ms/avm/moduletriage). {{% /notice %}} -1. When a new potential owner is identified, clarify the roles and responsibilities of the module owner: +1. 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: {{% expand title="➕ Standard AVM Core Team Reply to New Owners of an Orphaned Module" %}} @@ -244,8 +250,8 @@ To look for Orphaned Modules: - 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](https://aka.ms/avm/moduletriage) GitHub Project board. -3. Update the AVM Module Indexes, following the [process documented internally](https://dev.azure.com/CSUSolEng/Azure%20Verified%20Modules/_wiki/wikis/AVM%20Internal%20Wiki/684/Module-index-update-process). -4. Ensure every new owner has approved access through the [AVM Module Contributors access package](https://aka.ms/avm/id/access-package/module-contributor). See [SNFR20]({{% siteparam base %}}/spec/SNFR20) for the language-specific access requirements. No per-module GitHub team or `CODEOWNERS` changes are needed. +1. Submit a pull request adding the approved incoming handles to the `owners` array in the module's root `metadata.json`, linked to the orphaned module issue. Obtain approval from either metadata code-owner team and merge the change through the [metadata review process]({{% siteparam base %}}/contributing/module-metadata/#adopt-an-orphaned-module). +1. Ensure every new owner has approved access through the [AVM Module Contributors access package](https://aka.ms/avm/id/access-package/module-contributor). See [SNFR20]({{% siteparam base %}}/spec/SNFR20) for the language-specific access requirements. 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. @@ -265,7 +271,7 @@ To look for Orphaned Modules: {{% /expand %}} -9. When all actions detailed above are complete and confirmed, close the orphaned module issue with the following message: +1. Once the metadata change is reviewed and merged and all access and notice-removal actions above are complete, close the orphaned module issue with the following message. The module index updates automatically at the next four-hourly catalog sync. {{% expand title="➕ Closing remarks for the New Owner(s) of an Orphaned Module" %}} @@ -305,7 +311,7 @@ When the module owner needs to be changed without the module becoming orphaned, -  Status: Owners Identified 🤘  labels to the issue. - Module classification (resource/pattern/utility):  Class: Resource Module 📦 ,  Class: Pattern Module 📦  or  Class: Utility Module 📦  6. Make sure the issue is assigned to the "[AVM - Module Triage](https://github.com/orgs/Azure/projects/529)" 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. -7. Once the new owner provided their written consent in a comment by replying the text quoted in the message above, update the AVM Module Indexes, following the [process documented internally](https://dev.azure.com/CSUSolEng/Azure%20Verified%20Modules/_wiki/wikis/AVM%20Internal%20Wiki/684/Module-index-update-process). Confirm every incoming owner has approved access as described in [SNFR20]({{% siteparam base %}}/spec/SNFR20) before finalizing the handover. +1. Once each incoming owner's eligibility and written consent are confirmed, replace the departing handles with the approved incoming handles in the root `owners` array 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]({{% siteparam base %}}/contributing/module-metadata/#add-remove-or-transfer-owners). Confirm every incoming owner has approved access as described in [SNFR20]({{% siteparam base %}}/spec/SNFR20) before finalizing the handover. 8. Use the following text to finalize the new ownership transfer: {{% expand title="➕ Final Confirmation for the New Owner(s) of an Orphaned Module" %}} @@ -318,7 +324,7 @@ When the module owner needs to be changed without the module becoming orphaned, {{% /expand %}} -9. When all actions detailed above are complete and confirmed, close the orphaned module issue with the following message: +1. 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. {{% expand title="➕ Closing remarks for the New Owner(s) of an Orphaned Module" %}} @@ -340,7 +346,7 @@ If a module meets the criteria described in the "[Deprecated Modules]({{% sitepa 1. Submit a "deprecated module" issue by using the "[Deprecate AVM Module 🔴](https://aka.ms/avm/DeprecatedModule)" issue template. 2. 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](https://github.com/orgs/Azure/projects/529)" GitHub project. -3. Update the AVM Module Indexes, following the [process documented internally](https://dev.azure.com/CSUSolEng/Azure%20Verified%20Modules/_wiki/wikis/AVM%20Internal%20Wiki/684/Module-index-update-process). +1. 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** @@ -354,13 +360,23 @@ If a module meets the criteria described in the "[Deprecated Modules]({{% sitepa 1. Submit a Pull Request 1. For the AVM maintainers: Once the PR is merged, run the [.Platform - Publish [moduleIndex.json]](https://github.com/Azure/bicep-registry-modules/actions/workflows/platform.publish-module-index-json.yml) workflow with the `regenIndexFromBRM` flag set. This will de-list the module so that it won't show up in the VS-Code Bicep extension going forward. -Deprecating a module does not require changing `CODEOWNERS` or deleting a GitHub team. The shared `/avm/` entry and Module Contributors team are still required by other modules. +Deprecating a module does not require editing `CODEOWNERS` or deleting a GitHub team. The file is generated from module metadata, and the fallback `/avm/` entry is still required by other modules. **Terraform specific steps** 4. Place the information notice - with the text below - in the `README.md` file, in the module's root. 5. 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]({{% siteparam base %}}/contributing/module-metadata/#catalog-updates) 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/issue-template removal and registry-index update, or Terraform repository archival. + **Deprecation information notice** (to be place in the module's repository as described above) {{% expand title="➕ Deprecated module indicators" %}} diff --git a/docs/content/help-support/issue-triage/avm-organizer-bot.md b/docs/content/help-support/issue-triage/avm-organizer-bot.md index 613f3e9a2..38fd93434 100644 --- a/docs/content/help-support/issue-triage/avm-organizer-bot.md +++ b/docs/content/help-support/issue-triage/avm-organizer-bot.md @@ -62,7 +62,7 @@ The following scripts are leveraged by the **[Azure Verified Modules GitHub App] The following scripts are leveraged by the **[Azure Verified Modules GitHub App](https://github.com/apps/azure-verified-modules)** in the bicep-registry-modules ([BRM](https://aka.ms/BRM)) repository: -Module-specific routing uses the individual owners recorded in the [module indexes]({{% siteparam base %}}/indexes/bicep/), not `ModuleOwnersGHTeam` or membership of the shared Module Contributors team. The `Get-AvmModuleOwnerLogin.ps1` helper resolves `PrimaryModuleOwnerGHHandle` and `SecondaryModuleOwnerGHHandle`, inheriting ownership and orphan status through `ParentModule` for child modules. It normalizes and deduplicates handles and reports missing, duplicate, or invalid ownership metadata rather than treating it as an empty owner list. +Module-specific routing uses the individual owners recorded in each root module's `metadata.json`, not `ModuleOwnersGHTeam` or membership of the shared Module Contributors team. The generated [module indexes]({{% siteparam base %}}/indexes/bicep/) carry only the first two individual owners, so treat metadata as the source of truth and submit corrections through the [metadata review process]({{% siteparam base %}}/contributing/module-metadata/). The `Get-AvmModuleOwnerLogin.ps1` helper resolves `PrimaryModuleOwnerGHHandle` and `SecondaryModuleOwnerGHHandle`, inheriting ownership and orphan status through `ParentModule` for child modules. It normalizes and deduplicates handles and reports missing, duplicate, or invalid ownership metadata rather than treating it as an empty owner list. ### 1. Set-AvmGitHubIssueOwnerConfig.ps1 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 ef3c1b92f..94468d619 100644 --- a/docs/content/help-support/issue-triage/brm-issue-triage.md +++ b/docs/content/help-support/issue-triage/brm-issue-triage.md @@ -59,7 +59,7 @@ If the issue was opened as a misplaced module proposal, mention the `@Azure/azur 1. Check the Module issue: - Make sure the issue has the  Type: AVM 🅰️ ✌️ ⓜ️  applied to it. - - Use the AVM module indexes to identify the module owner(s) and make sure they are assigned/mentioned/informed. + - Use the AVM module indexes to locate the module and its root `metadata.json` for the full owner list. Make sure the owners are assigned/mentioned/informed. Submit corrections through the [metadata review process]({{% siteparam base %}}/contributing/module-metadata/). - If the module is orphaned (has no owner), make sure there's an orphaned module issue in the AVM repository. - Make sure the module's details are captured correctly in the description - i.e., name, classification (resource/pattern), language (Bicep/Terraform), etc. - Make sure the issue is categorized using one of the following type labels: 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 f4337a622..f5af94f8f 100644 --- a/docs/content/help-support/issue-triage/terraform-issue-triage.md +++ b/docs/content/help-support/issue-triage/terraform-issue-triage.md @@ -53,7 +53,7 @@ If the issue was opened as a misplaced module proposal, mention the `@Azure/azur ### Triaging a Module Issue 1. Check the Module issue: - - Use the AVM module indexes to identify the module owner(s) and make sure they are assigned/mentioned/informed. + - Use the AVM module indexes to locate the module and its root `metadata.json` for the full owner list. Make sure the owners are assigned/mentioned/informed. Submit corrections through the [metadata review process]({{% siteparam base %}}/contributing/module-metadata/). - If the module is orphaned (has no owner), make sure there's an orphaned module issue in the AVM repository. - Make sure the module's details are captured correctly in the description - i.e., name, classification (resource/pattern), language (Bicep/Terraform), etc. - Make sure the issue is categorized using one of the following type labels: @@ -70,6 +70,8 @@ If the issue was opened as a misplaced module proposal, mention the `@Azure/azur PR approvals are **enforced** on all AVM Terraform module repositories. The following rules apply to who must approve: +Changes to `metadata.json` require approval from an eligible member of either `@Azure/azure-verified-modules-engineering-owners` or `@Azure/azure-verified-modules-module-owners`, as described in the [metadata review process]({{% siteparam base %}}/contributing/module-metadata/#submit-and-review-a-change). Approval from both teams is not required, and being named in `owners` alone does not qualify a reviewer. The code-review requirements below apply to other changes in the same pull request. + 1. If the **PR is submitted by the module owner** and the **module is owned by a single person**, **another Terraform module owner must review and approve the PR** (the module owner cannot approve their own PR). - **First port of call:** find a friendly module owner from the [`azure-verified-modules-module-contributors`](https://aka.ms/avm/id/groups/module-contributors) Entra group and request a review. - **If no owner is available**, assign the `@Azure/azure-verified-modules-engineering-owners` GitHub team as a reviewer and apply the  Needs: Core Team 🧞  label so the AVM core team picks it up during triage. diff --git a/docs/content/resources/faq.md b/docs/content/resources/faq.md index d217679b6..b911047e8 100644 --- a/docs/content/resources/faq.md +++ b/docs/content/resources/faq.md @@ -279,7 +279,9 @@ If any of these queries don't return any results, it means that no module in the ### I want to become the owner of XYZ modules, where can I indicate this, and what are the expected actions from me? -If exists, you can comment on the [Module Proposal issue](https://aka.ms/AVM/ModuleProposals) of the module that you are interested in and the AVM Core Team will do the triage providing information about next steps. +For a proposed module, comment on its open [Module Proposal issue](https://aka.ms/AVM/ModuleProposals). For an existing module, follow the [ownership-change process]({{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#changing-module-owners), using the orphaned module issue when adopting an orphaned module. Do not reopen a closed module proposal. + +The AVM core team confirms eligibility and acceptance of the role. Add, remove, or transfer owners through a pull request to the root `metadata.json` using the [metadata review process]({{% siteparam base %}}/contributing/module-metadata/). Editing metadata does not grant access or review permission; follow [SNFR20]({{% siteparam base %}}/spec/SNFR20) separately. Having an understanding of roles & responsibilities is useful as well, you can find this information on the [Team Definitions & RACI | Azure Verified Modules]({{% siteparam base %}}/specs/shared/team-definitions/) page. diff --git a/docs/content/specs-defs/includes/shared/pattern/non-functional/PMNFR1.md b/docs/content/specs-defs/includes/shared/pattern/non-functional/PMNFR1.md index 5bbdd763e..031cdd92c 100644 --- a/docs/content/specs-defs/includes/shared/pattern/non-functional/PMNFR1.md +++ b/docs/content/specs-defs/includes/shared/pattern/non-functional/PMNFR1.md @@ -23,9 +23,11 @@ Pattern Modules **MUST** follow the below naming conventions (all lower case). {{% notice style="important" %}} -As part of the module proposal process, the module's approved name is captured both in the module proposal issue AND the related [module index page]({{% siteparam base %}}/indexes) (backed by the corresponding [CSV file](https://github.com/Azure/Azure-Verified-Modules/tree/main/docs/static/module-indexes)). +The module's approved name is captured in the module proposal issue. The related [module index page]({{% siteparam base %}}/indexes) and [CSV file](https://github.com/Azure/Azure-Verified-Modules/tree/main/docs/static/module-indexes) remain published lookup references. -Therefore, **module owners don't need to construct the module's name themselves, instead they need use the name prescribed in the module proposal issue or in the related CSV file, at the time of approval.** +**Module owners must use the name approved in the module proposal, not construct a new one.** If it differs from the index, confirm the correction with the AVM core team. + +Correct descriptive fields through the [metadata review process]({{% siteparam base %}}/contributing/module-metadata/). Changing `moduleDisplayName` does not rename the module or change its repository path. {{% /notice %}} diff --git a/docs/content/specs-defs/includes/shared/resource/non-functional/RMNFR1.md b/docs/content/specs-defs/includes/shared/resource/non-functional/RMNFR1.md index dee3cb76b..8a7f2a845 100644 --- a/docs/content/specs-defs/includes/shared/resource/non-functional/RMNFR1.md +++ b/docs/content/specs-defs/includes/shared/resource/non-functional/RMNFR1.md @@ -23,17 +23,19 @@ Resource modules **MUST** follow the below naming conventions (all lower case). {{% notice style="important" %}} -As part of the module proposal process, the module's approved name is captured both in the module proposal issue AND the related [module index page]({{% siteparam base %}}/indexes) (backed by the corresponding [CSV file](https://github.com/Azure/Azure-Verified-Modules/tree/main/docs/static/module-indexes)). +The module's approved name is captured in the module proposal issue. The related [module index page]({{% siteparam base %}}/indexes) and [CSV file](https://github.com/Azure/Azure-Verified-Modules/tree/main/docs/static/module-indexes) remain published lookup references. -Therefore, **module owners don't need to construct the module's name themselves, instead they need use the name prescribed in the module proposal issue or in the related CSV file, at the time of approval.** +**Module owners must use the name approved in the module proposal, not construct a new one.** If it differs from the index, confirm the correction with the AVM core team. + +Correct descriptive fields through the [metadata review process]({{% siteparam base %}}/contributing/module-metadata/). Changing `moduleDisplayName` does not rename the module or change its repository path. {{% /notice %}} {{% notice style="note" %}} -We will maintain a set of CSV files in the [AVM Central Repo (`Azure/Azure-Verified-Modules`)](https://github.com/Azure/Azure-Verified-Modules/tree/main/docs/static/module-indexes) with the correct singular names for all resource types to enable checks to utilize this list to ensure repos are named correctly. To see the formatted content of these CSV files with additional information, please visit the [AVM Module Indexes]({{% siteparam base %}}/indexes) page. +The CSV files in the [AVM Central Repo (`Azure/Azure-Verified-Modules`)](https://github.com/Azure/Azure-Verified-Modules/tree/main/docs/static/module-indexes) remain available for checks that use the approved singular resource names. To see their formatted content with additional information, visit the [AVM Module Indexes]({{% siteparam base %}}/indexes) page. -This will be updated quarterly, or ad-hoc as new RPs/ Resources are created and highlighted via a check failure. +Report missing or incorrect resource names to the AVM core team. Index corrections go through catalog generation and reviewed publication. {{% /notice %}} diff --git a/docs/content/specs-defs/includes/shared/shared/functional/SFR3.md b/docs/content/specs-defs/includes/shared/shared/functional/SFR3.md index 48dc50f59..2e10f6e53 100644 --- a/docs/content/specs-defs/includes/shared/shared/functional/SFR3.md +++ b/docs/content/specs-defs/includes/shared/shared/functional/SFR3.md @@ -50,9 +50,11 @@ This specification applies to all AVM module classes (resource, pattern, utility ### Bicep {{% notice style="important" %}} -We will maintain a set of CSV files in the [AVM Central Repo (`Azure/Azure-Verified-Modules`)](https://github.com/Azure/Azure-Verified-Modules/tree/main/docs/static/module-indexes) with the required TelemetryId prefixes to enable checks to utilize this list to ensure the correct IDs are used. To see the formatted content of these CSV files with additional information, please visit the [AVM Module Indexes]({{% siteparam base %}}/indexes) page. +Published CSV files in the [AVM Central Repo (`Azure/Azure-Verified-Modules`)](https://github.com/Azure/Azure-Verified-Modules/tree/main/docs/static/module-indexes) remain available for consumers and checks that look up assigned telemetry prefixes. To see their formatted content with additional information, visit the [AVM Module Indexes]({{% siteparam base %}}/indexes) page. -The value you need to use for your module is defined in the related module index. You can look it up on the index pages for [Resource Modules]({{% siteparam base %}}/indexes/bicep/bicep-resource-modules/#module-name-and-telemetry-id-prefix), [Pattern Modules]({{% siteparam base %}}/indexes/bicep/bicep-pattern-modules/#module-name-and-telemetry-id-prefix) and [Utility Modules]({{% siteparam base %}}/indexes/bicep/bicep-utility-modules/#module-name-and-telemetry-id-prefix). +Record the assigned prefix in `telemetryIdPrefix` in the module's `metadata.json`, including a child's own file when applicable. Keep it consistent with the module source and preserve existing identifiers. Corrections follow the [metadata review process]({{% siteparam base %}}/contributing/module-metadata/); assignment of a new identifier requires the AVM core team. + +Assigned values are also published in the [Resource Module]({{% siteparam base %}}/indexes/bicep/bicep-resource-modules/#module-name-and-telemetry-id-prefix), [Pattern Module]({{% siteparam base %}}/indexes/bicep/bicep-pattern-modules/#module-name-and-telemetry-id-prefix), and [Utility Module]({{% siteparam base %}}/indexes/bicep/bicep-utility-modules/#module-name-and-telemetry-id-prefix) indexes. Ask the AVM core team to resolve any discrepancy with metadata rather than inventing or replacing an identifier. {{% /notice %}} The ARM deployment name used for the telemetry **MUST** follow the pattern and **MUST** be no longer than 64 characters in length: `46d3xbcp..<(short) module name>..` diff --git a/docs/content/specs-defs/includes/shared/shared/non-functional/SNFR20.md b/docs/content/specs-defs/includes/shared/shared/non-functional/SNFR20.md index 0fa9f6564..a7ad7d33d 100644 --- a/docs/content/specs-defs/includes/shared/shared/non-functional/SNFR20.md +++ b/docs/content/specs-defs/includes/shared/shared/non-functional/SNFR20.md @@ -23,7 +23,7 @@ priority: 1110 All GitHub repositories that AVM modules are published from and hosted within **MUST** only assign GitHub repository permissions to GitHub teams. -Module ownership **MUST** be recorded in the respective [Module Indexes]({{% siteparam base %}}/indexes/). Per-module GitHub teams are not required; owner access is managed through the access package described below. +Module ownership **MUST** be recorded separately from access permissions. Maintain owners in the root `metadata.json` through the [metadata review process]({{% siteparam base %}}/contributing/module-metadata/). Owner access is managed through the access package described below. There **MUST NOT** be any GitHub repository permissions assigned to individual users. @@ -41,16 +41,22 @@ All Bicep module owners, including primary and secondary owners, **MUST** reques Your GitHub account **MUST** be [linked](https://repos.opensource.microsoft.com/link) to your corporate identity and be a member of the [Azure organization](https://repos.opensource.microsoft.com/orgs/Azure). -Once approved, access is granted through the [`azure-verified-modules-module-contributors`](https://aka.ms/avm/id/groups/module-contributors) Entra group and the corresponding [`@Azure/azure-verified-modules-module-contributors`](https://github.com/orgs/Azure/teams/azure-verified-modules-module-contributors) GitHub team. This shared access does not replace the individual module ownership and review responsibilities recorded in the module indexes. +Once approved, access is granted through the [`azure-verified-modules-module-contributors`](https://aka.ms/avm/id/groups/module-contributors) Entra group and the corresponding [`@Azure/azure-verified-modules-module-contributors`](https://github.com/orgs/Azure/teams/azure-verified-modules-module-contributors) GitHub team. This shared access does not replace individual module ownership and review responsibilities. Adding a handle to metadata does not grant this access. Bicep module owners **MUST** continue to work in forks of the [BRM repository](https://aka.ms/BRM). #### CODEOWNERS file -The BRM [`CODEOWNERS` file](https://github.com/Azure/bicep-registry-modules/blob/main/.github/CODEOWNERS) assigns `/avm/` to the shared `@Azure/azure-verified-modules-module-contributors` team. Module owners no longer need to create a GitHub team, request a parent-team assignment, or add a per-module `CODEOWNERS` entry when publishing or taking ownership of a module. +The BRM [`CODEOWNERS` file](https://github.com/Azure/bicep-registry-modules/blob/main/.github/CODEOWNERS) is generated automatically and **MUST NOT** be edited by hand. It assigns `/avm/` to the shared `@Azure/azure-verified-modules-module-owners` team as a fallback, then adds one entry per module path. + +Each module entry is built from that module's root `metadata.json`. Every handle in the `owners` array is listed as a code owner, in file order, followed by the fallback team. Both individual handles and `@Azure/team-slug` handles are supported, and there is no limit of two owners. Merging an ownership change through the [metadata review process]({{% siteparam base %}}/contributing/module-metadata/) is therefore what updates BRM review routing. The repository-wide default and the `*avm.core.team.tests.ps1` and `*.e2eignore` overrides remain assigned to `@Azure/azure-verified-modules-tooling-contributors`. +Changes to `metadata.json` require approval from an eligible member of either `@Azure/azure-verified-modules-engineering-owners` or `@Azure/azure-verified-modules-module-owners`. A `metadata.json` rule listing both teams is the last rule in the generated file, so it takes precedence over the per-module entries: a metadata change is reviewed by those teams rather than by the module's own owners, while the per-module entries continue to cover the rest of the module path. Either team can satisfy [metadata code-owner review]({{% siteparam base %}}/contributing/module-metadata/#submit-and-review-a-change); approval from both is not required. Being listed in metadata does not grant review permission. + +For Bicep and Terraform, both metadata code-owner teams must be visible and have repository write access. Access administration and environment approvals remain separate responsibilities. + {{% notice style="tip" %}} For the full onboarding process and ownership handover steps, see the [Bicep Owner Contribution Flow]({{% siteparam base %}}/contributing/bicep/bicep-contribution-flow/owner-contribution-flow/). {{% /notice %}} diff --git a/docs/content/specs-defs/includes/shared/shared/non-functional/SNFR8.md b/docs/content/specs-defs/includes/shared/shared/non-functional/SNFR8.md index 824c56c80..14a4be109 100644 --- a/docs/content/specs-defs/includes/shared/shared/non-functional/SNFR8.md +++ b/docs/content/specs-defs/includes/shared/shared/non-functional/SNFR8.md @@ -21,12 +21,12 @@ priority: 1100 ## ID: SNFR8 - Category: Contribution/Support - Module Owner(s) GitHub -A module **MUST** have at least one owner recorded in the respective [Module Indexes]({{% siteparam base %}}/indexes/). +A module **MUST** have at least one owner recorded in the root `metadata.json` file's `owners` array. Record every approved owner using bare individual handles or qualified handles for approved existing teams; children inherit that ownership. Changes require approval from either metadata code-owner team through the [metadata review process]({{% siteparam base %}}/contributing/module-metadata/). Today this is only Microsoft FTEs, but everyone is welcome to contribute. The module just **MUST** be owned by a Microsoft FTE (today) so we can enforce and provide the long-term support required by this initiative. {{% notice style="note" %}} -Module owners **MUST** obtain access through the Entra access package described in [SNFR20]({{% siteparam base %}}/spec/SNFR20). A separate GitHub team for each module is no longer required. +Module owners **MUST** obtain access through the Entra access package described in [SNFR20]({{% siteparam base %}}/spec/SNFR20). {{% /notice %}} diff --git a/docs/content/specs-defs/includes/shared/utility/UMNFR1.md b/docs/content/specs-defs/includes/shared/utility/UMNFR1.md index 231a4abd3..a63442308 100644 --- a/docs/content/specs-defs/includes/shared/utility/UMNFR1.md +++ b/docs/content/specs-defs/includes/shared/utility/UMNFR1.md @@ -23,9 +23,11 @@ Utility Modules **MUST** follow the below naming conventions (all lower case). {{% notice style="important" %}} -As part of the module proposal process, the module's approved name is captured both in the module proposal issue AND the related [module index page]({{% siteparam base %}}/indexes) (backed by the corresponding [CSV file](https://github.com/Azure/Azure-Verified-Modules/tree/main/docs/static/module-indexes)). +The module's approved name is captured in the module proposal issue. The related [module index page]({{% siteparam base %}}/indexes) and [CSV file](https://github.com/Azure/Azure-Verified-Modules/tree/main/docs/static/module-indexes) remain published lookup references. -Therefore, **module owners don't need to construct the module's name themselves, instead they need use the name prescribed in the module proposal issue or in the related CSV file, at the time of approval.** +**Module owners must use the name approved in the module proposal, not construct a new one.** If it differs from the index, confirm the correction with the AVM core team. + +Correct descriptive fields through the [metadata review process]({{% siteparam base %}}/contributing/module-metadata/). Changing `moduleDisplayName` does not rename the module or change its repository path. {{% /notice %}} diff --git a/docs/content/specs-defs/module-lifecycle.md b/docs/content/specs-defs/module-lifecycle.md index 4fcfbc2d8..9f2ca7075 100644 --- a/docs/content/specs-defs/module-lifecycle.md +++ b/docs/content/specs-defs/module-lifecycle.md @@ -87,6 +87,8 @@ It is critical to the consumers experience that modules continue to be maintaine To **orphan a module**, submit an [orphaned module](https://aka.ms/AVM/OrphanedModule) issue in the AVM repository. For the required steps, review the related article: [When a module becomes orphaned]({{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#when-a-module-becomes-orphaned). +Set `"owners": []` in the root `metadata.json` to remove all individual and team handles, following the [metadata review process]({{% siteparam base %}}/contributing/module-metadata/). Complete the issue and required notices; the four-hourly catalog sync then publishes the public index. + [When a new owner is identified]({{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#when-a-new-owner-is-identified), follow the related guidance. {{% /notice %}} @@ -140,6 +142,14 @@ The information notice **MUST** include the following statement: To **deprecate a module**, submit a [deprecated module](https://aka.ms/AVM/DeprecatedModule) issue in the AVM repository. For the required steps, review the related article: [When a module becomes deprecated]({{% siteparam base %}}/help-support/issue-triage/avm-issue-triage/#when-a-module-becomes-deprecated). +The catalog derives `Deprecated` from Bicep's `DEPRECATED.md` or the Terraform repository's `archived` flag. Complete the notices and other retirement steps above; the four-hourly [catalog sync]({{% siteparam base %}}/contributing/module-metadata/#catalog-updates) then publishes the change. + +A Bicep marker deprecates its module and all descendants. A child marker does not deprecate the parent or siblings. Archiving a Terraform repository deprecates every module entry in that repository. + +A module deprecated before it was ever published to the registry is removed from the indexes rather than listed as `Deprecated`. + +Changing owners does not deprecate or reactivate a module. + {{% /notice %}} {{% expand title="➕ Retrieve the available versions of a deprecated module" %}} diff --git a/docs/content/specs-defs/team-definitions.md b/docs/content/specs-defs/team-definitions.md index 05b1221ea..0a71fc674 100644 --- a/docs/content/specs-defs/team-definitions.md +++ b/docs/content/specs-defs/team-definitions.md @@ -54,7 +54,9 @@ Module owners are responsible for: - Module Feature Request Triage & Additions 4. **Managing additional module contributors** -Ideally there **SHOULD** be at least 2 module owners per module. Each owner **MUST** be recorded in the [module indexes]({{% siteparam base %}}/indexes/) and obtain access through the [AVM Module Contributors access package]({{% siteparam base %}}/spec/SNFR20). +Ideally there **SHOULD** be at least 2 module owners per module. Every approved owner **MUST** be recorded in the root `metadata.json` file's `owners` array through the [metadata review process]({{% siteparam base %}}/contributing/module-metadata/). + +Each owner **MUST** also obtain access through the [AVM Module Contributors access package]({{% siteparam base %}}/spec/SNFR20). Recording ownership in metadata does not grant access. ### Module Contributors diff --git a/docs/hugo.toml b/docs/hugo.toml index d54b6de26..964c3c8c8 100644 --- a/docs/hugo.toml +++ b/docs/hugo.toml @@ -721,12 +721,20 @@ pageRef = '/contributing/terraform/repository-setup' weight = 7 params = { alwaysopen = false, collapsibleMenu = true } +[[menu.defined]] +identifier = 'module-metadata' +parent = 'contributing' +name = 'Module Metadata' +pageRef = '/contributing/module-metadata' +weight = 4 +params = { alwaysopen = false, collapsibleMenu = true } + [[menu.defined]] identifier = 'contribution-qna' parent = 'contributing' name = 'Contribution Q&A' pageRef = '/contributing/q-and-a' -weight = 4 +weight = 5 params = { alwaysopen = false, collapsibleMenu = true } @@ -735,7 +743,7 @@ identifier = 'website-contribution' parent = 'contributing' name = 'Website' pageRef = '/contributing/website' -weight = 5 +weight = 6 params = { alwaysopen = false, collapsibleMenu = true } @@ -745,7 +753,7 @@ parent = 'contributing' pre = ' ' name = 'Code of Conduct' url = 'https://opensource.microsoft.com/codeofconduct/' -weight = 6 +weight = 7 params = { alwaysopen = false, collapsibleMenu = true } [[menu.defined]] @@ -754,7 +762,7 @@ parent = 'contributing' pre = ' ' name = 'Module Owner Onboarding' url = 'https://aka.ms/AVM/Onboarding' -weight = 7 +weight = 8 params = { alwaysopen = false, collapsibleMenu = true } [[menu.defined]] diff --git a/docs/static/includes/PR-approval-guidance.md b/docs/static/includes/PR-approval-guidance.md index 3c4aa130f..d44f4cb09 100644 --- a/docs/static/includes/PR-approval-guidance.md +++ b/docs/static/includes/PR-approval-guidance.md @@ -17,3 +17,5 @@ + +Changes to `metadata.json` require approval from an eligible member of either [`@Azure/azure-verified-modules-engineering-owners`](https://github.com/orgs/Azure/teams/azure-verified-modules-engineering-owners) or [`@Azure/azure-verified-modules-module-owners`](https://github.com/orgs/Azure/teams/azure-verified-modules-module-owners). Either team is sufficient; approval from both is not required. Being listed in the module's `owners` array does not by itself authorize approval. Follow the [metadata review process](https://azure.github.io/Azure-Verified-Modules/contributing/module-metadata/); code changes in the same pull request still need the normal reviews described above. diff --git a/docs/static/includes/msg-final-conf-new-orph-mod-owners.md b/docs/static/includes/msg-final-conf-new-orph-mod-owners.md index 03b8b418d..4ba68b9a1 100644 --- a/docs/static/includes/msg-final-conf-new-orph-mod-owners.md +++ b/docs/static/includes/msg-final-conf-new-orph-mod-owners.md @@ -6,11 +6,12 @@ We just want to ask you to double check a few important things. **Before taking ownership, confirm the following**: -- Every incoming owner must have approved access through the [Azure Verified Modules (AVM) Module Contributors access package](https://aka.ms/avm/id/access-package/module-contributor), as outlined in [SNFR20](https://azure.github.io/Azure-Verified-Modules/spec/SNFR20). There is no per-module GitHub team to take over or `CODEOWNERS` entry to update. +- Every incoming owner must have approved access through the [Azure Verified Modules (AVM) Module Contributors access package](https://aka.ms/avm/id/access-package/module-contributor), as outlined in [SNFR20](https://azure.github.io/Azure-Verified-Modules/spec/SNFR20). +- Confirm every approved incoming owner is recorded in the root `metadata.json` through a merged [metadata pull request](https://azure.github.io/Azure-Verified-Modules/contributing/module-metadata/) linked to this issue. Metadata does not grant access or review permission. - If applicable, remove the "Orphaned module" information notice from the module's `README.md` file as per [these instructions](https://azure.github.io/Azure-Verified-Modules/help-support/issue-triage/avm-issue-triage/#when-a-new-owner-is-identified) page. -- Please check back in a bit to make sure that your name has been updated in the [module index](https://azure.github.io/Azure-Verified-Modules/indexes/) page (this should happen shortly after you confirmed ownership). +- The [module index](https://azure.github.io/Azure-Verified-Modules/indexes/) is regenerated automatically every four hours. Check back to confirm your name appears once the metadata change is merged. -You're now the owner of this module and can start improving it as needed! ✅ Happy coding! 🎉 +Once the required ownership and access steps are confirmed, you can start improving the module as its owner! ✅ Happy coding! 🎉 Any further questions or clarifications needed, let us know! diff --git a/docs/static/includes/msg-final-conf-new-prop-mod-owners-bicep.md b/docs/static/includes/msg-final-conf-new-prop-mod-owners-bicep.md index 8757eac45..7939764f6 100644 --- a/docs/static/includes/msg-final-conf-new-prop-mod-owners-bicep.md +++ b/docs/static/includes/msg-final-conf-new-prop-mod-owners-bicep.md @@ -5,15 +5,17 @@ Thanks for confirming that you wish to own this AVM module and understand the re Before starting development, please ensure ALL the following requirements are met. -Every module owner must request and obtain approval for the [Azure Verified Modules (AVM) Module Contributors access package](https://aka.ms/avm/id/access-package/module-contributor), as outlined in [SNFR20](https://azure.github.io/Azure-Verified-Modules/spec/SNFR20#bicep). You no longer need to create per-module GitHub teams, assign parent teams, or add entries to `CODEOWNERS`. +Every module owner must request and obtain approval for the [Azure Verified Modules (AVM) Module Contributors access package](https://aka.ms/avm/id/access-package/module-contributor), as outlined in [SNFR20](https://azure.github.io/Azure-Verified-Modules/spec/SNFR20#bicep). -**Please use the following values explicitly as provided in the [module index](https://azure.github.io/Azure-Verified-Modules/indexes/) page**: +**Use the module name and path approved in the proposal, and the assigned telemetry identifier.** The [module index](https://azure.github.io/Azure-Verified-Modules/indexes/) remains a published lookup reference: - For your module: - `ModuleName` - for naming your module - `TelemetryIdPrefix` - for your module's [telemetry](https://azure.github.io/Azure-Verified-Modules/spec/SFR3) - Folder path are defined in `RepoURL`. +Maintain module details and the assigned `telemetryIdPrefix` in `metadata.json` through the [metadata review process](https://azure.github.io/Azure-Verified-Modules/contributing/module-metadata/). If an approved value is missing or conflicts with the index, contact the AVM core team. + 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! 🎉 diff --git a/docs/static/includes/msg-final-reply-new-orph-mod-owners.md b/docs/static/includes/msg-final-reply-new-orph-mod-owners.md index 0fe3e4785..53ce97474 100644 --- a/docs/static/includes/msg-final-reply-new-orph-mod-owners.md +++ b/docs/static/includes/msg-final-reply-new-orph-mod-owners.md @@ -1,6 +1,7 @@ - [x] Module Contributors access package approved for all incoming module owners. +- [x] Root metadata ownership change approved by either metadata code-owner team, merged, and linked to this issue through the [metadata review process](https://azure.github.io/Azure-Verified-Modules/contributing/module-metadata/). - [x] `ORPHANED` file deleted, `README` file updated. -The module index will be updated soon to reflect this change. +The module index is regenerated automatically every four hours, so the ownership change should appear shortly. Thank you for your work @replace_with_author! I'm closing this issue now. diff --git a/docs/static/includes/msg-final-reply-new-prop-mod-owners-bicep.md b/docs/static/includes/msg-final-reply-new-prop-mod-owners-bicep.md index 137d2afd8..31d795274 100644 --- a/docs/static/includes/msg-final-reply-new-prop-mod-owners-bicep.md +++ b/docs/static/includes/msg-final-reply-new-prop-mod-owners-bicep.md @@ -2,6 +2,6 @@ - [x] Module Contributors access package approved for all module owners. - [x] Issue template file updated. -The module index will be updated soon to reflect this change. +The AVM core team coordinates the module index through the [catalog sync](https://azure.github.io/Azure-Verified-Modules/contributing/module-metadata/#catalog-updates), which regenerates and publishes it automatically every four hours. Thank you for your work @replace_with_author! I'm closing this issue now.