Draft release notes for 3.2.0 and 3.1.2

[lornajane]

trafficstars

Opening this as a pull request purely as a good way to collaborate - DO NOT MERGE.

The content will be added to the github release.

[miqui]

@lornajane So far looks good to me.

[jeremyfiel]

should add more detailed info on new keywords in MediaType object.

[lornajane]

@jeremyfiel can you say something about what's missing? (I obviously don't know or it wouldn't be missing ...) I did just update with some of the changes from the last couple of weeks, but I don't think there is anything here that would match what you're asking for.

[handrews]

I'd like to propose a slightly different ordering to improve the storytelling around this release:

1. Our marquee features are improved tagging and *sequential/streaming support, and the latter of those is part of a pretty comprehensive update to data modeling and representation.
2. Expanded HTTP method support, self-identifying documents, and expanded OAuth support are our other major changes.
3. Improving the details and rigor of servers, paths, runtime expressions, and responses are "quality-of-life" improvements, to quote a recent Slack conversation.

This would give us a flow more like the following:

3.2 Updates

Tags

Data Modeling and Representation

OAS v3.2 makes significant progress towards more consistent, modular, and extensible media type and parameter support, while also expanding the set of media types supported in response to both emerging and legacy use cases. In addition, we have removed ambiguity regarding how to present examples in a variety of complex scenarios.

Media Type Registry

Sequential and Streaming Media Types

Parameters and Headers

Multipart Media Types

XML

Code Generation

Example Object

Additional Major Additions

Note: This subsection ordering within this section makes sense to me, but I do not feel strongly about it.

Methods

Document Identification and Reference Resolution

Security

Smaller Improvements

Servers, Paths, and Runtime Expressions

Responses

Updated to New Versions of Other Standards

etc.

[lornajane]

There's about 50% more spec change since I wrote this draft, re ordering definitely in our future! Thanks for the outline , I'll be trying to catch up this week

[lornajane]

Started adding the suggested structure (in 3 parts: digestible high level features, the masterpieces of data modeling, and then everything else), but I note that we don't have all the sections you mentioned @handrews , in particular:

• media types registry, these are the release notes on the specification and the media types registry isn't in this document so they're not included. Hold that thought for the blog content though
• code gen, I'm not sure what should go here
• multipart handling, how did I get this far without adding it? I have no idea but I've put a placeholder for now!

[lornajane]

@handrews Could you take a look at the multipart media types section I just added? We had it as **TODO** still!

[miqui]

@lornajane Nice job!! Looks GREAT to me.

[lornajane]

This is chaos, I'll be restructuring to make much slimmer release notes, an upgrade guide for the learn site and an announcement blog post (with the option to drill in with blog posts on more topics). I don't have a lot of time for the next week or so but I'll push updates when I can - since I'll mostly be moving content around, feedback on this current version is still very helpful if you have any

[lornajane]

Thank for all the brilliant reviews!! Split a bunch of the content out to become some new docs: https://github.com/OAI/learn.openapis.org/pull/137

[lornajane]

Thanks for all your input, the content became the release notes and also some documentation updates, so the pull requests is no longer needed