[REVIEW ONLY] Add written-word drafts since a PR is a good way to review #4095
Conversation
release-notes-3.1.1.md
Outdated
| - examples and additional documentation moved to https://learn.openapis.org | ||
| - the HTML rendering of the specification at https://spec.openapis.org is now considered the authoritative version (formerly it was the Markdown source on GitHub) | ||
|
|
||
| OpenAPI description writers should mark their OpenAPI descriptions with the version of OpenAPI specification they used to write their specification, updating where possible. |
There was a problem hiding this comment.
Why? Can this be explained more? (note that this is more of a request to description document authors than changes to 3.1.1, so perhaps break it out of this list?)
Co-authored-by: Darrel <darrmi@microsoft.com>
ralfhandl
dismissed stale reviews from earth2marsh and mikekistler
via
7c3faf6
Co-authored-by: Marsh Gardiner <marsh.gardiner@gmail.com>
including the two I missed before Co-authored-by: Marsh Gardiner <marsh.gardiner@gmail.com>
|
@mikekistler The release notes are almost identical for both versions, I ended up with nothing to add for 3.0.4, and just a few lines that are 3.1.1-only, these are clearly marked. We'll need to edit/remote them for each version accordingly when creating the releases. |
There was a problem hiding this comment.
Great work- I have some suggestions but I don't think there's anything here that I'd consider a blocker.
I feel like we should probably explain tooling expectations around the patch number in the openapi field more clearly somewhere, but I don't know that this is the place to do that.
| @@ -0,0 +1,68 @@ | |||
| OpenAPI Initiative is pleased to announce a patch release of the 3.0 and 3.1 OpenAPI specifications. | |||
| In patch releases, no changes are made to the way that APIs are described, but the specification wording itself contains many updates, expansions, and clarifications where previous the points may have been unclear or not covered. | |||
| Think of this release as the "Words Mean Things" edition. | |||
| ## Upgrade process | ||
|
|
||
| Most users and tool vendors should have no action to take, since the patch releases contain only wording changes or clarifications and no structure changes. | ||
| That said, especially if you publish OpenAPI tools, take a look at the release notes on GitHub to check that there are no surprises! |
There was a problem hiding this comment.
Since (if we move the sentence I mentioned earlier) we will have said that users don't need to make changes, should we re-focus this part on implementation? I also feel like maybe avoid "upgrade" because there technically shouldn't be a difference. I'm thinking something like the following:
Implementation Considerations
All clarifications in 3.0.4 and 3.1.1 apply to the entire 3.0 and 3.1 release lines, respectively, and there is no need for tools to check the patch version number in the openapi field. No new requirements have been added.
That said, these patch releases are unusually substantial, and tool developers may find details to implement that were not previously clear. In 3.1.1, the additional guidance around modeling generic data types and also around parsing documents and resolving references may (I don't know what words to use here... "be surprising?")
There was a problem hiding this comment.
Isn't this what I wrote?
There was a problem hiding this comment.
@lornajane I'm fine with leabing the text as-is, particularly if you don't see a distinction. TBH I wrote this review several days ago and then forgot to hit send so I don't quite recall why I was concerned. My obsessions over wording are often helpful in specification text, and much less so elsewhere 😅
| - Focuses on technical specifics by moving examples and additional documentation now published at [learn.openapis.org](https://learn.openapis.org) | ||
| - Declares that the HTML specifications at [spec.openapis.org](https://spec.openapis.org) are now the authoritative versions (formerly it was the Markdown source on GitHub) | ||
|
|
||
| OpenAPI Description writers should mark their OpenAPI Descriptions with the version of the OpenAPI specification they used to write their specification, updating where possible. |
There was a problem hiding this comment.
@earth2marsh commented that we needed to expand on this, but his remarks were lost in some of the reformatting. I'm not sure this belongs here in the release notes, should probably be in the announcement post instead.
There was a problem hiding this comment.
@lornajane agree on any expansion being more suitable for the announcement post.
In preparation for the release, please review (BUT DO NOT MERGE) the proposed wording for release notes and a blog post. I couldn't think of a better place to put words that we could all review, comment on and edit so I hope this makes sense. Pull request contains:
[3.1.1]are for that version only, I'll take the whole line out for the 3.0.4 release notes, and remove the indicator for the 3.1.1 ones - it just seemed easier than providing two almost-identical documents for you to reviewWith a big thankyou to @handrews for mining the epic diff to produce a huge starting point of information that I've tried to usefully summarise without eliminating all the detail!
The goal here is to check for mistakes and showstoppers; let's try not to polish forever. This one is NOT an authoritative document that must never be updated!