Merge pull request #28389 from microsoftgraph/main

Auto Publish – main to live - 2026-03-07 00:30 UTC

Author: learn-build-service-prod[bot]

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

@@ -0,0 +1,279 @@
+# Scenario 3: Document deprecated and retired APIs
+
+> **Before proceeding:** Read the shared standards and processes in [`common.md`](.github/prompts/author-api-docs/common.md). Use the `fetch` tool to open this file. It contains all shared setup steps, common processes (changelog, What's New, TOC, validation), reference standards, documentation standards, and the base quality checklist that apply to this scenario.
+
+---
+
+## Example interaction
+
+> **Author:** We need to deprecate the `outlookTask` resource and its methods. Blog post: https://devblogs.microsoft.com/... Deadline: August 20, 2025. Alternative: To Do API.
+>
+> **AI:** _[Reads common file, verifies branch]_
+> I'll process these deprecation changes:
+>
+> 1. Update `outlookTask` resource: add "(deprecated)" to H1, add CAUTION banner, add `toc.title` and `ROBOTS: NOINDEX`
+> 2. Mark all child methods as deprecated (6 method files)
+> 3. Update references in parent resources
+> 4. Update changelog and What's New
+>
+> Proceeding now.
+
+---
+
+## Prerequisites
+
+**See [temp-docstubs Folder](common.md#temp-docstubs-folder)** for instructions on setting up the temp-docstubs folder.
+
+For this scenario, the author should add these files to `temp-docstubs`:
+- Documentation Plan 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 Documentation Plan 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 (entire enum or specific enum members)
+- Actions
+- Functions
+
+## Inputs
+
+### Required inputs
+
+Ask the author to provide these in the `temp-docstubs` folder:
+
+**Documentation Plan (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
+
+### When the author provides context directly in their prompt
+
+If the author has already described the deprecation in sufficient detail (e.g., named specific resources, methods, or properties to deprecate, provided the alternative and deadline), you can work directly from their prompt instead of requesting formal inputs. In this case:
+
+| 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 |
+
+**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)
+
+## 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
+
+---
+
+## Deprecation guides
+
+### 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
+   - Add `ROBOTS: NOINDEX`  to YAML front matter
+
+2. **Mark child methods:**
+   - Add "(deprecated)" to H1 title in each method topic
+   - Add deprecation banner to each method topic
+   - Add `ROBOTS: NOINDEX`  to YAML front matter
+
+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 [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).
+
+---
+
+## 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
+
+In addition to the [base quality checklist](common.md#base-quality-checklist), verify:
+- [ ] "(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 — Scenario 3 specific:**
+- [ ] All deprecation items from Documentation Plan addressed