Merge branch 'main' into zallison/fix_createdByAppId_docs

Author: Danipocket

.gdn/.gdnbaselines

@@ -39,18 +39,6 @@
       "tool": "psscriptanalyzer",
       "ruleId": "PSAvoidUsingConvertToSecureStringWithPlainText",
       "createdDate": "2026-02-24 12:06:54Z"
-    },
-    "3a37bf64f23749ac738b5da94bdc0511f105855aee640971733d155dad1f9915": {
-      "signature": "3a37bf64f23749ac738b5da94bdc0511f105855aee640971733d155dad1f9915",
-      "alternativeSignatures": [],
-      "target": "scripts/update-permissions-reference-fic.ps1",
-      "line": 179,
-      "memberOf": [
-        "default"
-      ],
-      "tool": "psscriptanalyzer",
-      "ruleId": "PSAvoidUsingConvertToSecureStringWithPlainText",
-      "createdDate": "2026-03-24 12:06:54Z"
     }
   }
 }

.gdn/.gdnsuppress

@@ -39,18 +39,6 @@
       "tool": "psscriptanalyzer",
       "ruleId": "PSAvoidUsingConvertToSecureStringWithPlainText",
       "createdDate": "2026-02-24 12:06:54Z"
-    },
-    "3a37bf64f23749ac738b5da94bdc0511f105855aee640971733d155dad1f9915": {
-      "signature": "3a37bf64f23749ac738b5da94bdc0511f105855aee640971733d155dad1f9915",
-      "alternativeSignatures": [],
-      "target": "scripts/update-permissions-reference-fic.ps1",
-      "line": 179,
-      "memberOf": [
-        "default"
-      ],
-      "tool": "psscriptanalyzer",
-      "ruleId": "PSAvoidUsingConvertToSecureStringWithPlainText",
-      "createdDate": "2026-03-24 12:06:54Z"
     }
   }
 }

.github/prompts/author-api-docs/deprecate-retire.md

@@ -76,15 +76,15 @@ If the author has already described the deprecation in sufficient detail (e.g.,
 | Instead of... | Use... |
 |---------------|--------|
 | Documentation Plan | The author's prompt — extract what is being deprecated, the alternative/workaround, milestone date, and blog post link |
-| Autogenerated changelog | Ask the author if a changelog and What's New update are needed. If yes, use the [manual changelog authoring](common.md#manually-authoring-changelog-entries) process |
+| Autogenerated changelog | Changelog and What's New are **always required** for deprecations and retirements. If no autogenerated changelog file exists, use the [manual changelog authoring](common.md#manually-authoring-changelog-entries) process. Ask the author only for WorkloadArea and SubArea if not inferrable. |
 
 **What you still need from the author** (ask if not provided):
 - What specifically is being deprecated (resource, method, property, enum, etc.)
 - The alternative API or workaround
 - The milestone/sunset date
 - Blog post URL (if available)
 - Which version(s): beta, v1.0, or both
-- WorkloadArea and SubArea for the changelog (if one is needed)
+- WorkloadArea and SubArea for the changelog (if not inferrable)
 
 ## Key principles
 
@@ -190,10 +190,22 @@ See [Deprecating enumerations](.github/prompts/author-api-docs/enumerations.md#d
 
 ## Supporting updates
 
-**Changelog:** Change type: "Deprecation". Include API set/entities, link to topics and blog post. See [Updating the Changelog](common.md#updating-the-changelog).
+Changelog and What's New updates are always required for deprecations and retirements. This applies to all deprecated or retired schema artifacts — resources, properties, relationships, enums, methods.
+
+**Changelog:** Change type: "Deprecation" or "Deletion". Include API set/entities, link to topics and blog post. See [Updating the Changelog](common.md#updating-the-changelog).
 
 **What's New:** Describe deprecation, link to deprecated API and alternative, link to blog post. See [Updating What's New](common.md#updating-whats-new).
 
+**What's New description patterns for deprecations and retirements:**
+
+- **Deprecated resource:** `Deprecated the [resourceName](/graph/api/resources/{filename}?view=graph-rest-{version}&preserve-view=true) resource type. Use [alternativeName](/graph/api/resources/{alt-filename}?view=graph-rest-{version}&preserve-view=true) instead.`
+- **Deprecated property:** `Deprecated the **propertyName** property on the [resourceName](/graph/api/resources/{filename}?view=graph-rest-{version}&preserve-view=true) resource type. Use the **alternativeProperty** property instead.`
+- **Deprecated method:** `Deprecated the [methodName](/graph/api/{filename}?view=graph-rest-{version}&preserve-view=true) method. Use [alternativeMethod](/graph/api/{alt-filename}?view=graph-rest-{version}&preserve-view=true) instead.`
+- **Deprecated enum/member:** `Deprecated the `memberName` member in the **enumName** enumeration type.`
+- **Retired resource:** `Removed the **resourceName** resource type and associated methods.`
+
+For v1.0-only links, omit the `?view=graph-rest-beta&preserve-view=true` query string.
+
 ---
 
 ## Mixed scenarios
@@ -356,6 +368,7 @@ In addition to the [base quality checklist](common.md#base-quality-checklist), v
 **Supporting updates:**
 - [ ] Changelog: Change type "Deprecation", links to topics/blog
 - [ ] What's New: describes deprecation, links to API/alternative/blog
+- [ ] What's New includes entries for all deprecated schema artifacts (resources, properties, enums, methods)
 
 **Mixed scenarios:**
 - [ ] Non-deprecation tasks processed first

.github/prompts/author-api-docs/enumerations.md

@@ -89,7 +89,7 @@ Document within the **Properties** section of the resource that uses the enum. T
        ```
 
 2. **Create table:**
-   - Columns: **Member** and **Description**
+   - Columns: **Member** (required) and **Description** (optional)
    - List members in ascending order by numeric value (without exposing numeric values)
    - **For evolvable enums:**
      - Include `unknownFutureValue` member
@@ -133,7 +133,7 @@ Create a dedicated topic for the enumeration. This option is rarely applicable.
 2. **Add Members H2 section:**
    - **For evolvable enums (if members follow unknownFutureValue):**
      - Add introductory text before the table (same as Option 2)
-   - Table with columns: **Member** and **Description**
+   - Table with columns: **Member** (required) and **Description** (optional)
    - List members in ascending order by numeric value (without exposing values)
    - **For evolvable enums:**
      - Include `unknownFutureValue` member
@@ -257,21 +257,23 @@ Create a dedicated topic for the enumeration. This option is rarely applicable.
   - [ ] For evolvable enums with members after unknownFutureValue: Prefer header note included in property description
 - [ ] **Option 2 (Parent resource):**
   - [ ] H3 section "{enum-type} values" added after Properties table
-  - [ ] Table has Member and Description columns
+  - [ ] Table has Member column (required) and Description column (optional)
   - [ ] Members listed in ascending order by numeric value (values not exposed)
   - [ ] For evolvable enums: unknownFutureValue description is "Evolvable enumeration sentinel value. Do not use."
   - [ ] For evolvable enums with members after unknownFutureValue: Introductory text about Prefer header included
   - [ ] Properties table links to H3 section
+  - [ ] Parent resource property description excludes inline value listing (values are accessible via linked H3 section)
   - [ ] For subnamespaces: Fully qualified enum name used
 - [ ] **Option 3 (Separate topic):**
   - [ ] File created with correct naming convention
   - [ ] Title is "{enum-type} enum type"
   - [ ] Description mentions evolvable enumeration if applicable
-  - [ ] Members H2 section with Member and Description columns
+  - [ ] Members H2 section with Member column (required) and Description column (optional)
   - [ ] For evolvable enums: unknownFutureValue description is "Evolvable enumeration sentinel value. Don't use."
   - [ ] For evolvable enums with members after unknownFutureValue: Introductory text about Prefer header included
   - [ ] For subnamespaces: Namespace attribute added in page annotation
   - [ ] Parent resource Properties table links to enum topic
+  - [ ] Parent resource property description excludes inline value listing (values are accessible via linked enum topic)
 
 ### For updating existing enumerations
 

.github/prompts/author-api-docs/ga.md

@@ -70,13 +70,13 @@ If the author has already described the promotion in sufficient detail (e.g., na
 | Documentation Plan | The author's prompt — extract which resources, methods, or properties are being promoted |
 | API.md | The author's pasted content (XML, CSDL, JSON) + existing documentation in the repo |
 | Doc stubs | Existing files in the repo — search for them by resource name, namespace, or file path |
-| Autogenerated changelog | Ask the author if they can provide an autogenerated changelog in `temp-docstubs`. If not, use the [manual changelog authoring](common.md#manually-authoring-changelog-entries) process |
+| Autogenerated changelog | Changelog and What's New are **always required** for promotions to v1.0. If no autogenerated changelog file exists, use the [manual changelog authoring](common.md#manually-authoring-changelog-entries) process. Ask the author only for WorkloadArea and SubArea if not inferrable. |
 
 **What you still need from the author** (ask if not provided or inferrable):
 - Which specific resources/methods/properties are being promoted
 - Whether this is a full or partial promotion
 - Whether there are deviations from beta (renames, type changes, structural differences)
-- WorkloadArea and SubArea for the changelog (if one is needed)
+- WorkloadArea and SubArea for the changelog (if not inferrable)
 
 **Do not block** on missing formal inputs when the author's prompt provides enough context to proceed.
 
@@ -189,6 +189,8 @@ Remove "(preview)" from TOC entries as applicable:
 
 ### Step 5: Update changelog and What's new
 
+Changelog and What's New updates are always required for promotions. This applies to all promoted schema artifacts — resources, properties, relationships, enums, methods.
+
 1. **Add changelog entries:**
    - Use the autogenerated changelog doc stub (JSON file) provided by the author
    - Add entries for all APIs and resources being promoted to v1.0
@@ -198,6 +200,16 @@ Remove "(preview)" from TOC entries as applicable:
    - Add entries to the [What's new](https://learn.microsoft.com/en-us/graph/whats-new-overview) topic for the promoted APIs
    - Highlight that these APIs are now generally available (GA) in v1.0
 
+**What's New description patterns for GA promotions:**
+
+- **Promoted resource:** `Added the [resourceName](/graph/api/resources/{filename}) resource type to the v1.0 endpoint.`
+- **Promoted property:** `Added the **propertyName** property to the [resourceName](/graph/api/resources/{filename}) resource type in v1.0.`
+- **Promoted enum:** `Added the **enumName** enumeration type to the v1.0 endpoint.`
+- **Promoted method:** `Added the [methodName](/graph/api/{filename}) method to the [resourceName](/graph/api/resources/{filename}) resource type in v1.0.`
+- **Promoted enum member:** Added the `memberName` member to the **enumName** enumeration type in v1.0.
+
+Note: For v1.0 links, do NOT append `?view=graph-rest-beta&preserve-view=true` query strings.
+
 ## Partial promotions
 
 When only some properties, methods, or relationships of a resource are being promoted (the v1.0 resource already exists):
@@ -319,6 +331,7 @@ In addition to the [base quality checklist](common.md#base-quality-checklist), v
 **For changelog and What's new:**
 - [ ] Changelog entries added using autogenerated JSON stub
 - [ ] What's new topic updated with GA announcement
+- [ ] What's New includes entries for all promoted schema artifacts (resources, properties, enums, methods)
 
 **Final verification — Scenario 2 specific:**
 - [ ] All resource files promoted and updated

.github/prompts/author-api-docs/public-preview.md

@@ -67,7 +67,7 @@ If the author has already described the change in sufficient detail (e.g., paste
 | Documentation Plan | The author's prompt — extract scope, files, resources, and changes directly from their message |
 | API.md | The author's pasted content (XML, CSDL, JSON) + existing documentation in the repo |
 | Doc stubs | Existing files in the repo — search for them by resource name, namespace, or file path |
-| Autogenerated changelog | Ask the author if a changelog and What's New update are needed. If yes, use the [manual changelog authoring](common.md#manually-authoring-changelog-entries) process |
+| Autogenerated changelog | Changelog and What's New are **always required** for schema changes (new resources, properties, enums, methods, deprecations). If no autogenerated changelog file exists, use the [manual changelog authoring](common.md#manually-authoring-changelog-entries) process. Ask the author only for WorkloadArea and SubArea if not inferrable. |
 
 **What you still need from the author** (ask if not provided or inferrable):
 - Which version: beta, v1.0, or both
@@ -497,6 +497,30 @@ For all API changes, include the following updates as applicable:
 
 See the shared processes in [`common.md`](.github/prompts/author-api-docs/common.md) for complete instructions on each of these processes.
 
+### When changelog and What's New are required
+
+Changelog and What's New updates are required whenever a doc stub changelog file is provided or the Documentation Plan includes schema changes. This includes — but is not limited to:
+
+| Change type | Changelog required | What's New required |
+|-------------|-------------------|---------------------|
+| New resource type (EntityType, ComplexType) | ✅ Yes | ✅ Yes |
+| New API method (action, function) | ✅ Yes | ✅ Yes |
+| New property on existing resource | ✅ Yes | ✅ Yes |
+| New relationship on existing resource | ✅ Yes | ✅ Yes |
+| New enumeration type | ✅ Yes | ✅ Yes |
+| New enum member on existing enum | ✅ Yes | ✅ Yes |
+| Deprecation or removal | ✅ Yes | ✅ Yes |
+
+**What's New description patterns for common changes:**
+
+- **New resource:** `Added the [resourceName](/graph/api/resources/{filename}?view=graph-rest-beta&preserve-view=true) resource type.`
+- **New property:** `Added the **propertyName** property to the [resourceName](/graph/api/resources/{filename}?view=graph-rest-beta&preserve-view=true) resource type.`
+- **New enum:** `Added the **enumName** enumeration type.`
+- **New method:** `Added the [methodName](/graph/api/{filename}?view=graph-rest-beta&preserve-view=true) method to the [resourceName](/graph/api/resources/{filename}?view=graph-rest-beta&preserve-view=true) resource type.`
+- **New enum member:** `Added the `memberName` member to the **enumName** enumeration type.`
+
+For v1.0, omit the `?view=graph-rest-beta&preserve-view=true` query string from links.
+
 After gathering all inputs, analyze the Documentation Plan to understand the full scope of work.
 
 ## Quality checklist
@@ -594,6 +618,8 @@ In addition to the [base quality checklist](common.md#base-quality-checklist), v
 - [ ] All TOC changes made if applicable
 - [ ] All properties referencing updated enumerations have been updated
 - [ ] All permissions files copied
+- [ ] Changelog entry added for all schema changes (new resources, properties, enums, methods, deprecations)
+- [ ] What's New entry added for all schema changes (matches changelog scope)
 
 **For polymorphic collections (if applicable):**
 - [ ] Polymorphism detected from Documentation Plan notes