Add detailed versioning docs for single preview #3813
Conversation
|
No changes needing a change description found. |
|
You can try these changes here
|
markcowl
force-pushed
the
version-docs
branch
from
ea65c7e to
b1f95a6
Compare
website/src/content/docs/docs/howtos/ARM/versioning/03-stable-after-preview.md
Show resolved
Hide resolved
website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md
Outdated
Show resolved
Hide resolved
website/src/content/docs/docs/howtos/ARM/versioning/02-preview-after-preview.md
Outdated
Show resolved
Hide resolved
website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md
Show resolved
Hide resolved
website/src/content/docs/docs/howtos/ARM/versioning/07-perpetual-preview.md
Show resolved
Hide resolved
markcowl
force-pushed
the
version-docs
branch
from
b1f95a6 to
d31195d
Compare
haolingdong-msft
left a comment
haolingdong-msft
left a comment
There was a problem hiding this comment.
Thank you @markcowl for putting the versioning related documents together in this PR. It is really helpful and I've learnt a lot! left some comments for understanding and clarification purpose. Thank you so much for your guidance!
May I also ask two general questions?
- I saw there is also a versioning doc here: https://azure.github.io/typespec-azure/docs/howtos/versioning/preview-version/. Is this for data-plane? (Basically two versioning related documents in the typespec azure website, so I'm just a bit confused)
2. Does this PR include information in below two docs about versioning you've shared before? From my understanding, it includes, but just would like to confirm.
Rules for Versioning Decorators.loop
Scenarios for API Evolution.loop
| ~~v2025_12_01_preview: "2025-12-01-preview",~~ | ||
| v2026_01_01_preview: "2026-01-01-preview", | ||
|
|
||
| - Update any version documentation to use the new version |
There was a problem hiding this comment.
version documentation
Could I understand more on what does version documentation mean here? Does it mean all the wordings in @doc ?
There was a problem hiding this comment.
I think to be more precise, this should say "any mention of the api-version in documentation"
| - Change the name of the `examples` version folder for the latest preview to match the new preview version | ||
| - Make changes to the API description based on how the API has changed | ||
| - If any type that was introduced in the latest preview is _not_ in the new preview, simply remove the type | ||
| - If any other types are removed in this preview (unlikely) mark these with an `@removed` decorator referencing the new version |
There was a problem hiding this comment.
If any other types are removed in this preview
May I know what does 'this preview' mean? Is this latest preview or the new preview?
There was a problem hiding this comment.
Could I understand it as: If any other types are removed from latest stable (unlikely) mark these with an @removed decorator referencing the new version
There was a problem hiding this comment.
We whould use the 'new preview' language to disambiguate. I also wonder if a specific example might help to illustrate.
| - Make changes to the API description based on how the API has changed | ||
| - If any type that was introduced in the latest preview is _not_ in the new preview, simply delete the type | ||
| - If any other types are removed in this preview (unlikely) mark these with an `@removed` decorator referencing the new version | ||
| - If any types are added, renamed, or otherwise modified in the new version, mark them with the appropriate versioning decorator |
There was a problem hiding this comment.
Maybe we could add a link to 'versioning decorator'
| - If any types are added, renamed, or otherwise modified in the new version, mark them with the appropriate versioning decorator | |
| - If any types are added, renamed, or otherwise modified in the new version, mark them with the appropriate [versioning decorator](https://typespec.io/docs/libraries/versioning/reference/decorators/) |
There was a problem hiding this comment.
I do think we should have a doc reference here, but I think it should be the versioning doc, not the reference, as this doc discusses how to apply decorators for various kinds of changes
| - Add a new version to the `Versions` enum in your spec for the new preview. | ||
| - Decorate this version with the `@previewVersion` decorator from the `Azure.Core` library | ||
| - Make changes to the API description based on how the API has changed | ||
| - If any types are removed in this preview (unlikely) mark these with an `@removed` decorator referencing the new version |
There was a problem hiding this comment.
similar comments as above. 'this preview' is a little bit obsecure to me.
|
|
||
| - Add a new entry to the versions enum for the new stable version | ||
| - Update any version documentation to use the new version | ||
| - Change the name of the `examples` version folder for the latest preview to match the new stable version |
There was a problem hiding this comment.
Change the name of the
examplesversion folder for the latest preview to match the new stable version
Just to clarify my understanding: Does it mean change the name of the latest preview version folder under examples folder?
e.g.
There was a problem hiding this comment.
Yes, and a specific screen capture example would likely be useful
website/src/content/docs/docs/howtos/ARM/versioning/03-stable-after-preview.md
Show resolved
Hide resolved
| property: int32; | ||
| ``` | ||
| - For any type with an `@removed(p)` decorator, remove the decorator |
There was a problem hiding this comment.
Thank you @markcowl so much! I love these detailed examples on how to use the versioning decorators.
| title: Converting Existing Specs with Multiple Previews | ||
| --- | ||
|
|
||
| Converting a spec with multiple preview versions into a spec with a single, latest preview version is complex because the changes that occur in any |
There was a problem hiding this comment.
This process looks quite complex. Just curious, if a service has multiple previews nowadays, is this process a MUST if user later wants to add new preview version or new stable version?
There was a problem hiding this comment.
It is a must to adhere to the single preview version
| @@ -0,0 +1,59 @@ | |||
| --- | |||
| title: Immediately Replacing a Preview Version | |||
There was a problem hiding this comment.
Immediately Replacing a Preview Version
Could I learn more on what does this title mean? This doc to me seems more about 'adding a stable version, but still keep the preview version'?
There was a problem hiding this comment.
I think the first document provides the best description of this scenario - some service teams need to create a new preview version whenever they create a stable version. This involves preserving the changes in the last preview in the new preview and taking the parts of the last preview that have become stable and including them in the new stable version.
For most teams, the recommendation is to not create a stable version until all preview features have stabilized.
Yeah, one really important thing is that we make this documentation visible for those who need to see it. I think we might rename the existing doc to 'indicate that it is for 'data-plane only' and introduce another doc alongside it that is for arm, with links to the rest of this documentation. |
4 participants
No description provided.