Tracking for V3 Upgrade #3874

Tracking Issue for V3 Upgrades

#3873

V3 upgrade and release-readiness checklist

This checklist covers the full V3 upgrade, not only wrapper generation. Known follow-up identifies existing work or documented gaps; Validation identifies proposed release checks; Decision identifies policy or scope that needs agreement. These are not automatically all release blockers.

For each item, record an owner, linked issue/PR, completion criteria, and evidence. Mark complete only after those criteria are met; an open PR is not completion. Track approved deferrals with a rationale and user impact.

1. Runtime correctness

• Known follow-up: Resolve [v3 wrappers] Make session request-adapter caching Graph-profile-aware #3873: make session request-adapter caching Graph-profile-aware. Cover v1.0/beta in either order, interleaved/concurrent requests, same-profile reuse, and reconnect/context/disconnect lifecycle behavior.
• Validation: Verify supported authentication flows, Graph environments/service roots, session reuse, and explicit access-token behavior.
• Validation: Exercise cancellation, retry/throttling behavior, and actionable PowerShell error records.
• Validation: Verify list pagination and delta continuation, including query/header preservation and continuation-link profile/service-root validation.

2. Module and directive migration

• Known follow-up: Complete remaining module migration/audit PRs and record the disposition of every intended module/profile, including modules with no shared directives.
• Known follow-up: Track Align operation IDs for required shared directive paths #3847 (required-path operation-ID alignment) and Support compatible natural-ID operation variants #3849 (natural-ID GET parameter-set variants), and validate affected modules after landing.
• Known follow-up — before V3 release: Retire all temporary operation-ID migration tasks and migration-only tooling, evidence/ledger requirements, tests, and documentation once the migration is complete. Remove Align operation IDs for required shared directive paths #3847's tools/Utilities/RequiredPathOperationIds.json and its required-path correction hook in tools/Utilities/Set-OpenApiOperationIds.ps1, together with their dedicated regression tests and guidance. Restore the supported steady-state ID projection and verify normal specification refresh/generation and command/API compatibility without temporary migration corrections before release sign-off.
• Known follow-up: Inventory profile-local directives and global src/readme.graph.md directives, which the current shared-module migration excludes.
• Decision: Disposition deferred parameter aliases/transforms and schema/response directives: implement required behavior or explicitly document intentional changes.
• Validation: Reconcile migration ledgers with current specifications; distinguish a missing/excluded profile specification from a reviewed absence of API operations.

3. Command and API compatibility

• Validation: Refresh naming, route, export, parameter-set, and operation-coverage ledgers for both v1.0 and beta; do not rely on historical README counts.
• Decision: Classify differences as regressions, intentional corrections, new APIs, or retired APIs; agree on compatibility-sensitive naming and removed/renamed commands.
• Known follow-up: Review documented unsupported operation/body shapes and cross-path merges; implement or explicitly disposition each relevant release gap.
• Validation: Exercise complex request bodies, collections, enums, polymorphism, AdditionalProperties, pipeline binding, and response/output shapes with representative scripts.

4. PowerShell user experience

• Known follow-up: Generate per-cmdlet help and examples; verify Get-Help, Get-Command, parameter discovery, and example execution against V3.
• Known follow-up: Audit destructive commands for SupportsShouldProcess and verify -WhatIf/-Confirm behavior.
• Validation: Review output formatting/type information and script ergonomics rather than assuming V2 artifacts remain valid.

5. Platform support and quality gates

• Decision: Declare supported PowerShell versions, operating systems, and architectures.
• Known follow-up: Close the documented automated Windows PowerShell 5.1 gate gap if 5.1 remains supported; otherwise document and approve the support change.
• Validation: Run generator, migration, compiled-route/parity, body-omission, build/import, and runtime gates for the intended release surface.
• Validation: Run representative end-to-end scenarios across the supported matrix; distinguish stub-transport coverage from live-service validation.

6. Packaging and distribution

• Validation: Verify clean-machine install/import for individual modules and the aggregate distribution, including module names and dependency resolution.
• Validation: Verify runtime/Authentication/Kiota dependency loading and supported V2/V3, v1.0/beta, and adjacent-module coexistence scenarios.
• Validation: Verify manifests, exports, versions, signing, prerelease promotion, public publishing, and install/update/uninstall behavior. Existing internal-feed infrastructure alone does not establish public-release readiness.
• Validation: Confirm reproducible generation and release validation using pinned specification/tool inputs.

7. Performance and reliability

• Decision: Define acceptance budgets for installation/import, memory, first-command latency, large listings, and representative bulk operations.
• Validation: Compare against a declared V2 baseline and investigate material regressions.
• Validation: Exercise repeated connections, long-lived sessions, mixed profiles, and parallel activity for lifecycle/resource regressions.

8. Upgrade guidance and release decision

• Validation: Publish the V2-to-V3 upgrade guide: prerequisites, breaking changes, command/parameter mappings, request/response model changes, installation, and rollback.
• Validation: Publish known limitations and the user-visible impact/disposition of deferred work.
• Decision: Define preview/GA exit criteria, distinguish release blockers from approved deferrals, and record release sign-off with evidence.

Documentation migration and V2-to-V3 transition

• Validation: Inventory conceptual guides, cmdlet reference/help, API-reference snippets, samples, installation pages, and contributor/generation docs; assign owners and a V3 migration disposition.
• Decision: Define documentation versioning/navigation and V2/V3 coexistence; label preview versus GA and retain guidance for supported V2 users.
• Validation: Migrate cmdlet reference/help generation to the V3 surface; verify syntax, parameter sets, parameter types, return values, examples, and links against generated modules.
• Validation: Verify command metadata, API-reference snippet generation, and SDK example-import workflows consume the intended V3 inputs; regenerate and execute representative v1.0 and beta examples.
• Validation: Publish task-based before/after examples and command/parameter/type mappings, including intentionally removed or renamed APIs and behavior changes.
• Validation: Document clean upgrade, supported side-by-side installation, script/module version pinning, authentication/dependency considerations, and rollback to V2.
• Validation: Check inbound links, redirects, search/navigation, version selectors, and deprecation banners so users reach documentation for the correct SDK version.
• Decision: Define V2 maintenance/support policy and transition communications, including any deprecation timelines.
• Validation: Obtain documentation and migration-guide sign-off before V3 release.