-
Notifications
You must be signed in to change notification settings - Fork 9.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[REVIEW ONLY] Add written-word drafts since a PR is a good way to review #4095
base: main
Are you sure you want to change the base?
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Cool! Only minor nits.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good! 👍
Will the 3.0.4 releases be done in a separate PR or will they be added to this one?
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good overall! Some wordsmithing suggestions to consider.
Co-authored-by: Darrel <[email protected]>
7c3faf6
Co-authored-by: Marsh Gardiner <[email protected]>
including the two I missed before Co-authored-by: Marsh Gardiner <[email protected]>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@lornajane Looks good to me. Thanks.
@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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
❤️ 🤣
## 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Isn't this what I wrote?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@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 😅
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Many of @handrews' suggestions
- 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@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!