Reorganize versioning docs out of ARM subdirectory by Copilot · Pull Request #4217 · Azure/typespec-azure

Copilot · 2026-04-08T19:40:06Z

markcowl

In addition to the changes outlined in my review, look through the documents looking for examples, and, in each case where there is an example that would be significantly different for ARM versus data-plane (operations are significantly different for ARM versus data-plane APIs, for example)

Once changes are made, ensure that all files are correctly formatted, there are no misspellings, and no merge issues with main after you pull the latest changes.

Copilot · 2026-04-08T22:04:10Z

In addition to the changes outlined in my review, look through the documents looking for examples, and, in each case where there is an example that would be significantly different for ARM versus data...

Reviewed all documents for ARM vs data-plane differences. Added data-plane equivalents alongside ARM operation examples in:

06-evolving-apis.md — all operation examples (Simple Scenarios, Complex Scenarios, and Versioning Decorators sections) now show both ARM and data-plane patterns
getstarted/versioning.md — version declaration and all operation examples now show both ARM and data-plane patterns

Model-level examples (adding/removing properties, renaming, etc.) are unchanged since they work identically for both ARM and data-plane.

All files checked with codespell — no spelling issues. Merge with main verified clean. Done in c6aa80b.

markcowl · 2026-04-08T22:42:35Z

/azp run typspec-azure - PR Tools

azure-pipelines · 2026-04-08T22:42:43Z

No pipelines are associated with this pull request.

markcowl · 2026-04-09T01:45:45Z

/azp run typespec-azure - PR Tools

azure-pipelines · 2026-04-09T01:45:56Z

Azure Pipelines successfully started running 1 pipeline(s).

azure-sdk · 2026-04-09T01:47:34Z

No changes needing a change description found.

azure-sdk · 2026-04-09T01:55:42Z

You can try these changes here

🛝 Playground	🌐 Website

markcowl · 2026-04-13T23:45:59Z

@copilot please pull the latest from main, ensure there are no merge issues, and verify that only your changes are in the PR

Copilot · 2026-04-13T23:49:43Z

@copilot please pull the latest from main, ensure there are no merge issues, and verify that only your changes are in the PR

Rebased on latest main in 31077eb — no merge conflicts. Verified that only my documentation changes are in the PR (11 files, all under website/src/content/docs/).

markcowl

Make these changes, pull the latest from main, ensure that there are no merge conflicts, all files are correctly formatted, and the pr contains only your changes

Copilot · 2026-04-14T02:23:26Z

Make these changes, pull the latest from main, ensure that there are no merge conflicts, all files are correctly formatted, and the pr contains only your changes

All changes applied, rebased on latest main with no conflicts, verified only documentation changes are in the PR. Done in 2e94dc2.

catalinaperalta · 2026-04-16T23:41:12Z

+
+- [How to manage a single active preview if your service always has some features in preview (ARM only)](./uncommon-scenarios/02-perpetual-preview.md)
+
+## Should I Retain the OpenAPI for an Old Preview API (ARM Only)


I believe data-plane is doing this as well, at the very least I dont believe anybody is going back and removing old preview swaggers for dp either

They will actually be prevented from doing this by TypeSpec Validation, so my guess is that by and large they are not.

I just ran into a PR for a data plane that decided they needed to do this for no good reason because the documentation was there. I would really like to discourage everyone from leaving their old preview specs around, but for some ARM specs, doing so is potentially catastrophic

Is this a relatively new addition to typespec validation? I havent seen this enforced in any pr I've run across. This is an older spec on TypeSpec that has several older previews checked in, but only has the current stable versions in versioning enum: https://github.com/Azure/azure-rest-api-specs/blob/main/specification/cognitiveservices/ContentSafety/main.tsp

Another older service with this same issue: https://github.com/Azure/azure-rest-api-specs/blob/main/specification/ai/DocumentIntelligence/main.tsp

This service is in a slightly different boat because it still specifies all the previews in the api version enum: https://github.com/Azure/azure-rest-api-specs/blob/main/specification/ai/Face/main.tsp

so just wanted to call out that this doesnt seem to be enforced

markcowl

Make these changes, pull the latest from main, validate that all files are correctly formateed and only your changes are in the PR

…ntroductions, update links Agent-Logs-Url: https://github.com/Azure/typespec-azure/sessions/e3f6341b-5c80-4f75-8fe5-e8b9a30074e8 Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

…ll references Agent-Logs-Url: https://github.com/Azure/typespec-azure/sessions/5ae43f24-5a9b-4ac4-9c08-9ef4240f81c4 Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

Agent-Logs-Url: https://github.com/Azure/typespec-azure/sessions/5ae43f24-5a9b-4ac4-9c08-9ef4240f81c4 Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

…e examples, update headings Agent-Logs-Url: https://github.com/Azure/typespec-azure/sessions/83ebf765-92d4-4c47-8eab-eb4aa807c173 Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

…Required section, apply suggestions, remove data-plane examples Agent-Logs-Url: https://github.com/Azure/typespec-azure/sessions/56c71242-0384-4237-b485-c9d866377d88 Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

…ting Agent-Logs-Url: https://github.com/Azure/typespec-azure/sessions/6fc3dfbd-f127-4697-8ab5-5d2db938f57d Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

…tion, move Note to ARM section Agent-Logs-Url: https://github.com/Azure/typespec-azure/sessions/557330e7-cce9-4916-94ca-12a9636bc60c Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

Copilot · 2026-04-21T00:34:33Z

Make these changes, pull the latest from main, validate that all files are correctly formateed and only your changes are in the PR

All review changes applied, rebased on latest main, all files pass prettier formatting, and only versioning doc changes are in the PR diff. Done in 9282536.

markcowl · 2026-04-21T00:41:28Z

/azp run typespec-azure - PR Tools

azure-pipelines · 2026-04-21T00:41:38Z

Azure Pipelines successfully started running 1 pipeline(s).

catalinaperalta

dp additions lgtm :)

Copilot AI assigned Copilot and markcowl Apr 8, 2026

Copilot created this pull request from a session on behalf of markcowl April 8, 2026 19:40 View session

microsoft-github-policy-service bot added the meta:website TypeSpec.io updates label Apr 8, 2026

Copilot started work on behalf of markcowl April 8, 2026 19:45 View session

Copilot AI requested a review from markcowl April 8, 2026 19:51

Copilot finished work on behalf of markcowl April 8, 2026 19:51

markcowl requested changes Apr 8, 2026

View reviewed changes

Copilot started work on behalf of markcowl April 8, 2026 21:46 View session

Copilot AI requested a review from markcowl April 8, 2026 22:04

Copilot finished work on behalf of markcowl April 8, 2026 22:04

Copilot started work on behalf of markcowl April 13, 2026 23:46 View session

Copilot AI force-pushed the copilot/reorganize-versioning-documents branch from c6aa80b to 31077eb Compare April 13, 2026 23:49

Copilot finished work on behalf of markcowl April 13, 2026 23:50

markcowl requested changes Apr 14, 2026

View reviewed changes

Copilot started work on behalf of markcowl April 14, 2026 02:15 View session

Copilot finished work on behalf of markcowl April 14, 2026 02:23

Copilot AI requested a review from markcowl April 14, 2026 02:23

Copilot started work on behalf of markcowl April 14, 2026 20:27 View session

Copilot finished work on behalf of markcowl April 14, 2026 21:32

Copilot started work on behalf of markcowl April 14, 2026 23:01 View session

Copilot finished work on behalf of markcowl April 15, 2026 00:25

microsoft-github-policy-service bot added the eng label Apr 15, 2026

Copilot AI force-pushed the copilot/reorganize-versioning-documents branch from 1cbd017 to 637db28 Compare April 15, 2026 00:32

catalinaperalta reviewed Apr 16, 2026

View reviewed changes

Comment thread website/src/content/docs/docs/howtos/Versioning/uncommon-scenarios/02-perpetual-preview.md

catalinaperalta reviewed Apr 16, 2026

View reviewed changes

markcowl requested changes Apr 21, 2026

View reviewed changes

Copilot started work on behalf of markcowl April 21, 2026 00:29 View session

Copilot AI and others added 7 commits April 21, 2026 00:31

Reorganize versioning docs: move ARM docs to Versioning root, merge i…

e013930

…ntroductions, update links Agent-Logs-Url: https://github.com/Azure/typespec-azure/sessions/e3f6341b-5c80-4f75-8fe5-e8b9a30074e8 Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

Move ARM/versioning.md to Versioning/06-evolving-apis.md and update a…

c874dfe

…ll references Agent-Logs-Url: https://github.com/Azure/typespec-azure/sessions/5ae43f24-5a9b-4ac4-9c08-9ef4240f81c4 Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

Add link to general versioning guidance in perpetual-preview doc

3c43914

Agent-Logs-Url: https://github.com/Azure/typespec-azure/sessions/5ae43f24-5a9b-4ac4-9c08-9ef4240f81c4 Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

Address review feedback: remove data-plane section, add ARM/data-plan…

04234d2

…e examples, update headings Agent-Logs-Url: https://github.com/Azure/typespec-azure/sessions/83ebf765-92d4-4c47-8eab-eb4aa807c173 Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

Add URL redirects for reorganized versioning documents and fix format…

025d883

…ting Agent-Logs-Url: https://github.com/Azure/typespec-azure/sessions/6fc3dfbd-f127-4697-8ab5-5d2db938f57d Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

Address review: move links to end, promote heading, apply text sugges…

9282536

…tion, move Note to ARM section Agent-Logs-Url: https://github.com/Azure/typespec-azure/sessions/557330e7-cce9-4916-94ca-12a9636bc60c Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>

Copilot AI force-pushed the copilot/reorganize-versioning-documents branch from 637db28 to 9282536 Compare April 21, 2026 00:33

Copilot finished work on behalf of markcowl April 21, 2026 00:34

Copilot AI requested a review from markcowl April 21, 2026 00:34

markcowl approved these changes Apr 21, 2026

View reviewed changes

markcowl marked this pull request as ready for review April 21, 2026 00:41

markcowl requested review from bterlson and timotheeguerin as code owners April 21, 2026 00:41

catalinaperalta approved these changes Apr 21, 2026

View reviewed changes


		- [How to manage a single active preview if your service always has some features in preview (ARM only)](./uncommon-scenarios/02-perpetual-preview.md)

		## Should I Retain the OpenAPI for an Old Preview API (ARM Only)

Conversation

Copilot AI commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

markcowl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Apr 8, 2026

Uh oh!

markcowl commented Apr 8, 2026

Uh oh!

azure-pipelines bot commented Apr 8, 2026

Uh oh!

markcowl commented Apr 9, 2026

Uh oh!

azure-pipelines bot commented Apr 9, 2026

Uh oh!

azure-sdk commented Apr 9, 2026

Uh oh!

azure-sdk commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

markcowl commented Apr 13, 2026

Uh oh!

Copilot AI commented Apr 13, 2026

Uh oh!

markcowl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Apr 14, 2026

Uh oh!

Uh oh!

catalinaperalta Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

markcowl Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

catalinaperalta Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

markcowl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Apr 21, 2026

Uh oh!

markcowl commented Apr 21, 2026

Uh oh!

azure-pipelines bot commented Apr 21, 2026

Uh oh!

catalinaperalta left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Copilot AI commented Apr 8, 2026 •

edited

Loading

azure-sdk commented Apr 9, 2026 •

edited

Loading

markcowl Apr 20, 2026 •

edited

Loading