Merge pull request #28031 from microsoftgraph/main

Merge to publish.

Author: Danipocket

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

@@ -15,11 +15,14 @@ Before beginning the documentation process, first ask the author which documenta
 **Please select your documentation scenario:**
 1. Author fresh APIs / fresh API changes to beta
 2. Promote APIs from beta to v1.0
+3. Document deprecated APIs
 
-**Please respond with 1 or 2 to proceed.**
+**Please respond with 1, 2, or 3 to proceed.**
 
 Once the author responds, follow the appropriate workflow below.
 
+**Note:** Scenario 3 (deprecation) can be combined with Scenario 1 or 2. If the Summary of API changes includes both deprecation and other changes (new APIs, promotions, updates), the workflow will handle mixed scenarios by processing non-deprecation tasks first, then applying deprecation documentation.
+
 ---
 
 ## Common Setup and Processes
@@ -76,11 +79,56 @@ After authoring documentation, update the appropriate changelog file in the `cha
   }
   ```
 
-**Step 3: Copy changelog records**
-- Copy the ChangeList records from the autogenerated changelog
-- Add them to the appropriate changelog file in the `changelog/` folder
-- Ensure the WorkloadArea and SubArea match the autogenerated file
-- Use "beta" for Version in Scenario 1, "v1.0" for Version in Scenario 2
+**Step 3: Copy the complete changelog record**
+- **IMPORTANT:** A changelog record is NOT just the ChangeList array. A complete changelog record consists of:
+  - `ChangeList` array (containing individual change items)
+  - `Id` (unique GUID for this set of changes)
+  - `Cloud` (e.g., "Prod")
+  - `Version` (e.g., "beta" or "v1.0")
+  - `CreatedDateTime` (ISO-8601 DateTime)
+  - `WorkloadArea` (e.g., "Security")
+  - `SubArea` (may be empty string)
+
+- **How to copy the record:**
+  1. Open the autogenerated changelog file from `temp-docstubs/` (e.g., `changelog_*.json` or `Microsoft.*.json`)
+  2. Locate the complete record object inside the `"changelog"` array (usually lines 3 to the closing brace of that object)
+  3. Copy the ENTIRE record object, including:
+     - Opening brace `{`
+     - The complete `ChangeList` array with all its items
+     - All metadata properties (`Id`, `Cloud`, `Version`, `CreatedDateTime`, `WorkloadArea`, `SubArea`)
+     - Closing brace `}`
+  4. Open the target changelog file in `changelog/{prefix}.json`
+  5. Paste the complete record as the FIRST item in the `"changelog"` array (after the opening `[`)
+  6. Ensure proper JSON formatting with commas between records
+
+- **Example of what to copy (complete record):**
+  ```json
+  {
+    "ChangeList": [
+      {
+        "Id": "1e2218aa-5dbc-4c74-a0fe-1d06e90b451c",
+        "ApiChange": "Property",
+        "ChangedApiName": "newProperty",
+        "ChangeType": "Addition",
+        "Description": "Added the **newProperty** property...",
+        "Target": "resourceName"
+      }
+    ],
+    "Id": "1e2218aa-5dbc-4c74-a0fe-1d06e90b451c",
+    "Cloud": "Prod",
+    "Version": "beta",
+    "CreatedDateTime": "2026-01-07T08:37:50.5865153Z",
+    "WorkloadArea": "Security",
+    "SubArea": ""
+  }
+  ```
+
+- **DO NOT:**
+  - Copy only the ChangeList items and insert them into an existing record
+  - Modify the Id, CreatedDateTime, or other metadata from the autogenerated file
+  - Create a new record structure manually
+
+- **Result:** The changelog file should have the new record added at the beginning of the changelog array, with all subsequent records following it
 
 ### Common Process: Updating What's New
 
@@ -230,8 +278,8 @@ For this scenario, the author should add these files to `temp-docstubs`:
 
 ### Additional prerequisites
 After gathering the inputs, you must also prompt the author to provide:
-- **author**: The value to use in the front matter `author` field across all new files
-- **ms.subservice**: The value to use in the front matter `ms.subservice` field across all new files
+- **author**: Value to replace TODO placeholders in the `author` field (only for new files or where TODO exists)
+- **ms.subservice**: Value to replace TODO placeholders in the `ms.subservice` field (only for new files or where TODO exists)
 
 ### Critical guidance on doc stubs
 
@@ -514,6 +562,243 @@ Remove "(preview)" from TOC entries as applicable:
 
 ---
 
+## Scenario 3: Document deprecated APIs
+
+### Prerequisites
+
+**See [Common Setup: temp-docstubs Folder](#common-setup-temp-docstubs-folder)** for instructions on setting up the temp-docstubs folder.
+
+For this scenario, the author should add these files to `temp-docstubs`:
+- Summary of API changes documenting what is being deprecated
+- Autogenerated changelog file (changelog_*.json) if applicable
+- Any supporting documentation about the deprecation (blog post URLs, alternative APIs, migration guidance)
+
+### Understanding API deprecation
+
+A feature that is no longer in active development is _deprecated_. Deprecations are announced via blog posts and corresponding documentation updates. The deprecation announcement includes:
+- A timeline (deprecation period) after which the feature is removed from the service or the service is retired
+- Alternative features or workarounds for existing apps
+- Migration guidance and timelines
+
+**Important:** Deprecation is not always a standalone process. An API can be deprecated in the same set of changes that add new APIs. For example:
+- Deprecating one property while adding a replacement property
+- Deprecating a method while adding a new method
+- Deprecating a resource while adding an alternative resource
+- Combining deprecation with other API additions or updates
+
+The Summary of API changes may contain a mix of deprecation and new API documentation tasks.
+
+**API artifacts that can be deprecated:**
+- Resources (Entity Types and Complex Types)
+- Methods (CRUD operations, actions, functions)
+- Properties
+- Relationships (Navigation Properties)
+- Parameters (path, function, or query parameters)
+- Enumerations
+
+### Inputs required
+
+**Summary of API changes (required):**
+- Detailed description of what is being deprecated, which files to change, alternatives/workarounds, milestone dates, and blog post links
+- May include both deprecation and non-deprecation changes (mixed scenarios)
+- **Location:** `temp-docstubs` folder
+
+**Autogenerated changelog (optional):**
+- JSON file if provided
+- **Location:** `temp-docstubs` folder
+
+### Key principles
+
+- **Customer clarity:** Clearly indicate what is deprecated and provide alternatives/workarounds
+- **Implicit deprecation:** Deprecating a resource implies all its properties, methods, and relationships are deprecated (no need to mark each individually)
+- **Type definitions:** Deprecating a resource does NOT deprecate child type definitions unless explicitly stated
+
+### Common deprecation patterns
+
+**Deprecation banner (applies to resources, methods, enumerations with own topics):**
+- Place immediately after namespace declaration (before beta disclaimer if beta)
+- Format as CAUTION alert
+- Include: what's deprecated, milestone date, alternative/workaround, blog post link
+- Use include files stored in `api-reference/includes/` for consistency across topics
+
+**Example:**
+```markdown
+> [!CAUTION]
+> The Outlook tasks API is deprecated and will stop returning data on August 20, 2022. Use the [To Do API](https://learn.microsoft.com/graph/api/resources/todo-overview?view=graph-rest-1.0) instead.
+```
+
+**Table updates (applies to properties, relationships, parameters, enum members):**
+- Add "(deprecated)" to the name in the first column
+- Update description with alternative/workaround
+- Move to end of table, grouped alphabetically with other deprecated items
+- Do NOT add "(deprecated)" to JSON representation sections (causes validation errors)
+
+**TOC updates:**
+- Add `toc.title` attribute in YAML front matter with "(deprecated)" OR
+- Include "(deprecated)" inside link text in Methods tables
+
+---
+
+### To deprecate a resource
+
+1. **Update resource topic:**
+   - Add "(deprecated)" to H1 title: `# user resource type (deprecated)`
+   - Add deprecation banner (see common pattern above)
+   - Add `toc.title` with "(deprecated)" to YAML front matter
+
+2. **Mark child methods:**
+   - Add "(deprecated)" to H1 title in each method topic
+   - Add deprecation banner to each method topic
+
+3. **Update references in other resources:**
+   - Add "(deprecated)" to properties/relationships/methods that reference the deprecated resource type
+
+4. **Do NOT mark child type definitions as deprecated** (only if explicitly stated in Summary)
+
+---
+
+### To deprecate a method
+
+1. **Update method topic:**
+   - Add "(deprecated)" to H1 title: `# Delete user (deprecated)`
+   - Add deprecation banner with alternative/workaround
+
+2. **Update parent resource Methods table:**
+   - Add "(deprecated)" inside link text: `[Delete (deprecated)](user-delete.md)`
+   - Move to end of table (grouped alphabetically with other deprecated methods)
+   - Include alternative in description column
+
+---
+
+### To deprecate a property
+
+1. **Update resource Properties table:**
+   - Add "(deprecated)" to property name, update description with alternative, move to end (see common pattern)
+
+2. **Update API method topics:**
+   - Add "(deprecated)" in Request body tables (POST, PATCH, PUT) if property is used
+   - Update Response examples: remove property if no longer returned, keep if still returned
+
+---
+
+### To deprecate a relationship
+
+1. **Update resource Relationships table:**
+   - Add "(deprecated)" to relationship name, update description, move to end (see common pattern)
+
+2. **Deprecate corresponding methods:**
+   - Methods including the navigation property as a segment are also deprecated
+   - Follow method deprecation workflow for each affected method
+
+---
+
+### To deprecate a parameter
+
+**Update parameter table in method topic:**
+- Add "(deprecated)" to parameter name, specify whether to ignore or use alternative, move to end (see common pattern)
+
+---
+
+### To deprecate an enumeration
+
+1. **Update enumeration definition:**
+   - **In enums.md or parent resource:** Add "(deprecated)" to section title: `### emailType values (deprecated)`
+   - **In own topic (rare):** Add "(deprecated)" to H1 title and add deprecation banner
+
+2. **Update properties using the enum:**
+   - Update type, description, possible values with alternative/workaround
+
+---
+
+### To deprecate enumeration members
+
+1. **Update member table:**
+   - Add "(deprecated)" to member name, specify alternative, move to end (see common pattern)
+
+2. **Update property descriptions:**
+   - Note which values are deprecated and provide guidance
+
+---
+
+### Supporting updates
+
+**Changelog:** Change type: "Deprecation". Include API set/entities, link to topics and blog post. See [Common Process: Updating the Changelog](#common-process-updating-the-changelog).
+
+**What's New:** Describe deprecation, link to deprecated API and alternative, link to blog post. See [Common Process: Updating What's New](#common-process-updating-whats-new).
+
+---
+
+### Mixed scenarios
+
+When combining deprecation with new APIs/promotions:
+1. Categorize changes (deprecation, new, promotion, updates)
+2. Process non-deprecation tasks first (ensures alternatives are documented)
+3. Process deprecation tasks, referencing newly created alternatives
+4. Update changelog with both deprecation and addition/change entries
+
+---
+
+### Version-specific notes
+
+- **Beta:** Banner after namespace, before beta disclaimer; keep beta disclaimer; use `?view=graph-rest-beta&preserve-view=true`
+- **v1.0:** Banner after namespace; no query strings in links
+- **Both:** Apply to both versions; may have different milestone dates/alternatives
+
+---
+
+### Quality checklist
+
+**Common to all deprecations:**
+- [ ] "(deprecated)" added to H1 titles or table entries as appropriate
+- [ ] Deprecation banners added (resources, methods, enums with own topics): CAUTION alert after namespace, includes milestone/alternative/blog link
+- [ ] Include files used for banner text (best practice)
+- [ ] TOC updated: `toc.title` in YAML or "(deprecated)" in link text
+- [ ] Alternatives/workarounds provided and linked
+- [ ] "(deprecated)" NOT added to JSON representation sections
+
+**Table entries (properties, relationships, parameters, enum members):**
+- [ ] "(deprecated)" added to name in first column
+- [ ] Description updated with alternative
+- [ ] Moved to end of table (grouped alphabetically with other deprecated items)
+
+**Resources:**
+- [ ] All child methods marked deprecated with banners
+- [ ] References in other resources marked "(deprecated)"
+- [ ] Child type definitions NOT marked deprecated (unless explicitly stated)
+
+**Relationships:**
+- [ ] Corresponding methods with navigation property as segment also deprecated
+
+**Properties:**
+- [ ] "(deprecated)" added in Request body tables (POST/PATCH/PUT) if applicable
+- [ ] Response examples updated (removed if no longer returned, kept if still returned)
+- [ ] Description accuracy reviewed (e.g., "required" removed)
+
+**Enumerations:**
+- [ ] Section title or H1 title updated
+- [ ] Properties using enum updated with alternatives
+
+**Supporting updates:**
+- [ ] Changelog: Change type "Deprecation", links to topics/blog
+- [ ] What's New: describes deprecation, links to API/alternative/blog
+
+**Mixed scenarios:**
+- [ ] Non-deprecation tasks processed first
+- [ ] Deprecation references newly created alternatives
+- [ ] Changelog includes both deprecation and addition entries
+
+**Version-specific:**
+- [ ] Beta: Banner before beta disclaimer; beta disclaimer retained; links include `?view=graph-rest-beta&preserve-view=true`
+- [ ] V1.0: No query strings in links
+- [ ] Both versions: Applied to both with version-specific formatting
+
+**Final:**
+- [ ] All Summary items addressed
+- [ ] No markdown lint errors
+- [ ] Summary provided to author
+
+---
+
 ## Categories of changes (Scenario 1 only)
 
 Based on the summary of API changes, the work will fall into two categories:
@@ -707,9 +992,10 @@ When authoring or updating documentation, ensure compliance with these standards
 Before working on any file, apply these rules to both resource and API files:
 
 ### Front matter
-- **Replace TODO placeholders:**
-  - Use the `author` value provided by the author
-  - Use the `ms.subservice` value provided by the author
+- **Replace TODO placeholders only:**
+  - If `author` field has TODO: replace with author-provided value
+  - If `ms.subservice` field has TODO: replace with author-provided value
+  - Do NOT update these fields if they already contain values
 - **[Optional] Improve the description:**
   - Make it user-friendly and clear
   - Use information from API.md to enhance it
@@ -718,6 +1004,7 @@ Before working on any file, apply these rules to both resource and API files:
   - `ms.date`
   - `doc_type`
   - `ms.localizationpriority`
+  - `author` and `ms.subservice` if already populated
 
 ### File body
 - **H1 title:** Leave unchanged