Skip to content

docs(versioning): fix stable-after-preview guidance for @previewVersion ordering#4498

Draft
Copilot wants to merge 3 commits into
mainfrom
copilot/fix-versioning-doc-inaccuracy
Draft

docs(versioning): fix stable-after-preview guidance for @previewVersion ordering#4498
Copilot wants to merge 3 commits into
mainfrom
copilot/fix-versioning-doc-inaccuracy

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented May 26, 2026

The stable-after-preview how-to instructed authors to add a new stable version and remove @previewVersion later as a separate step. This produces a diagnostic because @previewVersion must only decorate the last version in the enum—adding a stable version after it violates that constraint.

Changes

  • First step: Instruct authors to remove @previewVersion from the preview version and add the new stable version as the last enum entry (keeping the preview version so the spec still compiles during editing)
  • Later step: Add explicit instruction to remove the old preview version from the enum after all decorator updates are complete

Corrected flow

// Step 1: Remove @previewVersion, add stable as last entry
enum Versions {
- @Azure.Core.previewVersion
  `2025-10-01-preview`,
+ `2026-01-01`,
}

// Step 2 (after decorator updates): Remove old preview
enum Versions {
- `2025-10-01-preview`,
  `2026-01-01`,
}

Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>
@microsoft-github-policy-service microsoft-github-policy-service Bot added the meta:website TypeSpec.io updates label May 26, 2026
Copilot AI changed the title [WIP] Fix versioning documentation for stable versions docs(versioning): correct stable-after-preview guidance for @previewVersion ordering May 26, 2026
Copilot AI requested a review from markcowl May 26, 2026 17:55
Copy link
Copy Markdown
Member

@markcowl markcowl left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull the latest from main, make these changes, ensure that all changed files are correctly formatted, this branch is up to date with the main branch and only the changes associated with this pr are in the pr diff.

## Making Changes to your TypeSpec spec

- Add a new entry to the versions enum for the new stable version
- Replace the latest preview entry in the versions enum with the new stable version, and remove `@previewVersion` in the same edit to avoid diagnostics
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here you should instruct the user to remove the @previewVersion decorator from the preview version and add the new stable version as the last entry in the enum.

If you remove the preview version, the spec will fail to compile, which will make editing difficult.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated in the latest commit. The first step now instructs users to remove @previewVersion and add the new stable version as the last enum entry, keeping the preview version in place so compilation still works.


```diff lang=tsp
enum Versions {
- @Azure.Core.previewVersion
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here, we should only instruct the user to remove the replaced preview version (since we will have removed the @previewVersion decorator above)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added a step here that instructs the user to remove only the replaced preview version from the enum (since @previewVersion was already removed in the first step).

…ator first

Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com>
Copy link
Copy Markdown
Contributor Author

Copilot AI commented May 27, 2026

Pull the latest from main, make these changes, ensure that all changed files are correctly formatted, this branch is up to date with the main branch and only the changes associated with this pr are in...

Done. Pulled latest from main, made the requested changes, verified formatting is correct, and confirmed only the relevant doc file is in the diff.

Copilot AI changed the title docs(versioning): correct stable-after-preview guidance for @previewVersion ordering docs(versioning): fix stable-after-preview guidance for @previewVersion ordering May 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

meta:website TypeSpec.io updates

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[doc] Update versioning doc for adding a new stable version after a preview version

2 participants