module deprecation (#1942)

Author: matebarabas

.github/ISSUE_TEMPLATE/5_orphaned_module.yml

@@ -1,7 +1,7 @@
-name: Orphaned AVM Module 👀
+name: Orphaned AVM Module 🟡
 description: An existing AVM module has just become orphaned and needs a new owner
 title: "[Orphaned Module]: `MODULE_NAME_BETWEEN_BACKTICKS`"
-labels: ["Status: Module Orphaned :eyes:", "Needs: Module Owner :mega:", "Needs: Triage :mag:"]
+labels: ["Status: Module Orphaned :yellow_circle:", "Needs: Module Owner :mega:", "Needs: Triage :mag:"]
 projects: ["Azure/529"]
 body:
   - type: markdown

.github/ISSUE_TEMPLATE/6_module_deprecation.yml

@@ -0,0 +1,68 @@
+name: Deprecate AVM Module 🔴
+description: Want to deprecate an AVM Module? Let us know!
+title: "[Module Deprecation]: `MODULE_NAME_BETWEEN_BACKTICKS`"
+labels: ["Status: Module Deprecated :red_circle:", "Needs: Triage :mag:"]
+projects: ["Azure/529"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        By filling this issue template, you're requesting a given AVM module to be [deprecated](https://azure.github.io/Azure-Verified-Modules/specs/shared/module-lifecycle/#deprecated-modules).
+
+        This request should primarily be submitted by the module owner, but can be submitted by anyone. The module owner will be contacted to confirm the deprecation request.
+
+  - type: checkboxes
+    id: existing-checks
+    attributes:
+      label: Check for previous/existing GitHub issues/deprecation requests
+      description: By submitting this issue, you confirm that you have [searched for previous/existing GitHub issues/module deprecation requests](https://github.com/Azure/Azure-Verified-Modules/issues?q=is%3Aissue+sort%3Aupdated-desc+) to avoid creating a duplicate.
+      options:
+        - label: I have checked for previous/existing GitHub issues/module deprecation requests.
+          required: true
+  - type: checkboxes
+    id: existing-module-from-elsewhere
+    attributes:
+      label: Check this module isn't already deprecated in the module indexes
+      description: By submitting this issue, you confirm that you have checked the [Bicep](https://azure.github.io/Azure-Verified-Modules/indexes/bicep/) or [Terraform](https://azure.github.io/Azure-Verified-Modules/indexes/terraform/) module indexes for the module you are requesting to be deprecated.
+      options:
+        - label: I have checked for that this module isn't already deprecated.
+          required: true
+  - type: dropdown
+    id: language
+    attributes:
+      label: Bicep or Terraform?
+      description: Is this a Bicep or a Terraform module? (Please submit a separate deprecation request for each language!)
+      options:
+        - Bicep
+        - Terraform
+    validations:
+      required: true
+  - type: input
+    id: module-name
+    attributes:
+      label: Module Name
+      description: |
+        Please provide the exact name of the module you're requesting to be deprecated.
+      placeholder: '<Module name>'
+    validations:
+      required: true
+  - type: textarea
+    id: module-details
+    attributes:
+      label: Module Details
+      description: Let us know why this module should be deprecated!
+    validations:
+      required: true
+  - type: input
+    id: owner-gh-un
+    attributes:
+      label: Module Owner's GitHub Username (handle)
+      description: Please provide the GitHub handle of the current module owner!
+    validations:
+      required: false
+  - type: markdown
+    attributes:
+      value: |
+        > **NOTE**:
+        >
+        > - This module deprecation request issue **MUST remain open** until the module deprecation process if fully completed. **Do NOT close** the issue before receiving confirmation from the AVM Core team!

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

@@ -164,13 +164,7 @@ Once module is developed and `v0.1.0` has been published to the relevant registr
 
 ### When a module becomes orphaned
 
-If a module meets the criteria described in the "[Orphaned AVM Modules]({{% siteparam base %}}/specs/shared/module-lifecycle/#orphaned-avm-modules)" chapter, the modules is considered to be orphaned and the below steps must be performed.
-
-An issue is considered to be an orphaned module if
-
-- it was opened through the "[Orphaned AVM Module 👀](https://aka.ms/avm/OrphanedModule)" template,
-- it has the labels of &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#FBCA04;">Needs: Triage 🔍</mark>&nbsp;, &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#FF0019;color:white;">Needs: Module Owner 📣</mark>&nbsp; and the &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#F4A460;">Status: Module Orphaned 👀</mark>&nbsp; applied to it, and
-- it is assigned to the "[AVM - Module Triage](https://github.com/orgs/Azure/projects/529)" GitHub project.
+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.
 
 {{% notice style="note" %}}
 The original **Module Proposal issue** related to the module in question **MUST remain closed and intact**.
@@ -180,8 +174,8 @@ 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 %}}
 
-1. Create a new issue using the "[Orphaned AVM Module 👀](https://aka.ms/AVM/OrphanedModule)" issue template.
-2. Make sure the &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#FBCA04;">Needs: Triage 🔍</mark>&nbsp;, &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#FF0019;color:white;">Needs: Module Owner 📣</mark>&nbsp;, and the &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#F4A460;">Status: Module Orphaned 👀</mark>&nbsp; labels are assigned to the issue.
+1. Submit an "orphaned module" issue by using the "[Orphaned AVM Module 🟡](https://aka.ms/AVM/OrphanedModule)" issue template.
+2. Make sure the &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#FBCA04;">Needs: Triage 🔍</mark>&nbsp;, &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#FF0019;color:white;">Needs: Module Owner 📣</mark>&nbsp;, and the &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#F4A460;">Status: Module Orphaned 🟡</mark>&nbsp; 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).
 5. Place an information notice as per the below guidelines:
@@ -196,7 +190,7 @@ Include the following text in the information notice:
 
 {{% expand title="➕ Orphaned module notice for module README file" %}}
 
-{{< highlight lineNos="false" type="markdown" wrap="true" title="" >}}
+{{< highlight lineNos="false" type="markdown" wrap="true" title="ORPHANED.md" >}}
 
 {{% include file="/static/includes/orphaned-module-notice.md" %}}
 
@@ -211,7 +205,7 @@ Include the following text in the information notice:
 {{% notice style="tip" %}}
 To look for Orphaned Modules:
 
-- Click on the following link to use this saved query ➡️ <a href="https://aka.ms/avm/OrphanedModules">&nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#F4A460;">Status: Module Orphaned 👀</mark>&nbsp;</a> ⬅️.
+- Click on the following link to use this saved query ➡️ <a href="https://aka.ms/avm/OrphanedModules">&nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#F4A460;">Status: Module Orphaned 🟡</mark>&nbsp;</a> ⬅️.
 - Check the `Orphaned` swim lane on the [Module Triage board](https://aka.ms/avm/moduletriage).
 {{% /notice %}}
 
@@ -230,7 +224,7 @@ To look for Orphaned Modules:
 
 2. Once the new module owner candidate has confirmed they understand and accept their roles and responsibilities as an AVM module owner
     - Assign the issue to the confirmed module owner.
-    - Remove the &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#F4A460;">Status: Module Orphaned 👀</mark>&nbsp; and the &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#FF0019;color:white;">Needs: Module Owner 📣</mark>&nbsp; labels from the issue.
+    - Remove the &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#F4A460;">Status: Module Orphaned 🟡</mark>&nbsp; and the &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#FF0019;color:white;">Needs: Module Owner 📣</mark>&nbsp; labels from the issue.
     - Add the &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#C8E6C9;">Status: Module Available 🟢</mark>&nbsp; and &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#FBEF2A;">Status: Owners Identified 🤘</mark>&nbsp; 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).
@@ -256,6 +250,38 @@ To look for Orphaned Modules:
 
 7. Close the Orphaned Module issue.
 
+## Deprecated modules
+
+### When a module becomes deprecated
+
+If a module meets the criteria described in the "[Deprecated Modules]({{% siteparam base %}}/specs/shared/module-lifecycle/#4-deprecated-modules)" chapter, the module is considered to be deprecated and the below steps must be performed.
+
+1. Submit a "deprecated module" issue by using the "[Deprecate AVM Module 🔴](https://aka.ms/avm/DeprecatedModule)" issue template.
+2. Make sure the &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#FBCA04;">Needs: Triage 🔍</mark>&nbsp; and the &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#000000;color:white;">Status: Module Deprecated 🔴</mark>&nbsp; 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).
+4. 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 `DEPRECATED.md` file, in the module's root.
+      - Run the [`utilities/tools/Set-AVMModule.ps1`](https://github.com/Azure/bicep-registry-modules/blob/main/utilities/tools/Set-AVMModule.ps1) utility with the module path as an input. This re-generates the module’s `README.md` file, so that the `README.md` file will also contain the same notice in its header.
+      - Make sure the content of the `DEPRECATED.md` file is displayed in the `README.md` in its header (right after the title).
+      - Publish a new patch version, having the updated `README.md` stating the module is deprecated.
+    - In case of a Terraform module:
+      - Place the information notice - with the text below - in the `README.md` file, in the module's root.
+      - Archive the module's repository on GitHub.
+    - Once the information notice is placed, submit a Pull Request.
+
+Place the following information notice in the module's repository:
+
+{{% expand title="➕ Deprecated module indicators" %}}
+
+{{< highlight lineNos="false" type="markdown" wrap="true" title="DEPRECATED.md" >}}
+
+{{% include file="/static/includes/deprecated-module-notice.md" %}}
+
+{{< /highlight >}}
+
+{{% /expand %}}
+
 ## General feedback/question, documentation update and other standard issues
 
 An issue is a "General Question/Feedback ❔" if it was opened through the ["General Question/Feedback ❔"](https://github.com/Azure/Azure-Verified-Modules/issues/new?assignees=&labels=Type%3A+Question%2FFeedback+%3Araising_hand%3A&projects=&template=question_feedback.yml&title=%5BQuestion%2FFeedback%5D%3A+) issue template, and has the labels of &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#CB6BA2;color:white;">Type: Question/Feedback 🙋‍♀️</mark>&nbsp; and &nbsp;<mark style="background-image:none;white-space: nowrap;background-color:#FBCA04;">Needs: Triage 🔍</mark>&nbsp; applied to it.

docs/content/indexes/_index.md

@@ -12,12 +12,20 @@ The following table shows the number of all available, orphaned and planned **AV
 
 {{% moduleStats language="All" moduleType="All" showLanguage=true showClassification=true %}}
 
+{{% expand title="➕ Additional information" %}}
+
+{{% notice style="grey" title="Legend" %}}
+{{% include file="/static/includes/module-status-legend.md" %}}
+{{% /notice %}}
+
+{{% /expand %}}
+
 {{% notice style="tip" title="Want to contribute to AVM modules?" %}}
 
 | #  | <div style="width:250px">Labels</div> | Link and description |
 | -------- | -------- | -------- |
 | 1.   | <mark style="background-image:none;white-space: nowrap;background-color:#ADD8E6;">Type: New Module Proposal 💡</mark> <br> <mark style="background-image:none;white-space: nowrap;background-color:#FF0019;color:white;">Needs: Module Owner 📣</mark> | To become the **owner of a new module**, see [all new modules looking for owners](https://aka.ms/AVM/NeedsModuleOwner) or check out the "*Looking for owners*" swimlane [here](https://aka.ms/AVM/NeedsModuleOwner/Project).   |
-| 2.   | <mark style="background-image:none;white-space: nowrap;background-color:#F4A460;">Status: Module Orphaned 👀</mark>    | To become the **owner of an orphaned module**, see [all orphaned modules](https://aka.ms/AVM/OrphanedModules) or check out the "*Orphaned*" swimlane [here](https://aka.ms/AVM/OrphanedModules/Project).   |
+| 2.   | <mark style="background-image:none;white-space: nowrap;background-color:#F4A460;">Status: Module Orphaned 🟡</mark>    | To become the **owner of an orphaned module**, see [all orphaned modules](https://aka.ms/AVM/OrphanedModules) or check out the "*Orphaned*" swimlane [here](https://aka.ms/AVM/OrphanedModules/Project).   |
 | 3.   | <mark style="background-image:none;white-space: nowrap;background-color:#C95474;color:white;">Needs: Module Contributor 📣</mark>  | To become a **co-owner or contribute to a module**, see [all modules looking for contributors](https://aka.ms/AVM/NeedsModuleContributor). |
 
 For more details on "**What are the different ways to contribute to AVM?**", see [here]({{% siteparam base %}}/faq/#are-there-different-ways-to-contribute-to-avm).

docs/content/indexes/bicep/_index.md

@@ -12,12 +12,20 @@ The following table shows the number of all available, orphaned and planned **Bi
 
 {{% moduleStats language="Bicep" moduleType="All" showLanguage=true showClassification=true %}}
 
+{{% expand title="➕ Additional information" %}}
+
+{{% notice style="grey" title="Legend" %}}
+{{% include file="/static/includes/module-status-legend.md" %}}
+{{% /notice %}}
+
+{{% /expand %}}
+
 {{% notice style="tip" title="Want to contribute to AVM Bicep modules?" %}}
 
 | #  | Labels | Link and description |
 | -------- | -------- | -------- |
 | 1.   | <mark style="background-image:none;white-space: nowrap;background-color:#ADD8E6;">Type: New Module Proposal 💡</mark> <br> <mark style="background-image:none;white-space: nowrap;background-color:#FF0019;color:white;">Needs: Module Owner 📣</mark> <br> <mark style="background-image:none;white-space: nowrap;background-color:#1D73B3;color:white;">Language: Bicep 💪</mark>  | To become the **owner of a new Bicep module**, see [all new Bicep modules looking for owners](https://aka.ms/AVM/Bicep/NeedsModuleOwner) or check out the "*Looking for owners*" swimlane [here](https://aka.ms/AVM/Bicep/NeedsModuleOwner/Project). |
-| 2.   | <mark style="background-image:none;white-space: nowrap;background-color:#F4A460;">Status: Module Orphaned 👀</mark> <mark style="background-image:none;white-space: nowrap;background-color:#1D73B3;color:white;">Language: Bicep 💪</mark>   | To become the **owner of an orphaned Bicep module**, see [all orphaned Bicep modules](https://aka.ms/AVM/Bicep/OrphanedModules) or check out the "*Orphaned*" swimlane [here](https://aka.ms/AVM/Bicep/OrphanedModules/Project).   |
+| 2.   | <mark style="background-image:none;white-space: nowrap;background-color:#F4A460;">Status: Module Orphaned 🟡</mark> <mark style="background-image:none;white-space: nowrap;background-color:#1D73B3;color:white;">Language: Bicep 💪</mark>   | To become the **owner of an orphaned Bicep module**, see [all orphaned Bicep modules](https://aka.ms/AVM/Bicep/OrphanedModules) or check out the "*Orphaned*" swimlane [here](https://aka.ms/AVM/Bicep/OrphanedModules/Project).   |
 | 3.   | <mark style="background-image:none;white-space: nowrap;background-color:#C95474;color:white;">Needs: Module Contributor 📣</mark> <mark style="background-image:none;white-space: nowrap;background-color:#1D73B3;color:white;">Language: Bicep 💪</mark> | To become a **co-owner or contribute to a Bicep module**, see [all Bicep modules looking for contributors](https://aka.ms/AVM/Bicep/NeedsModuleContributor). |
 
 For more details on "**What are the different ways to contribute to AVM?**", see [here]({{% siteparam base %}}/faq/#are-there-different-ways-to-contribute-to-avm).