3.x minor release approach

[handrews]

We know we want to do a 3.2 release, and talked in this week's TDC Call about the possibility of further 3.x releases.

As with the patch releases (see #3528), I think the overarching goal should be smoothing the path to Moonwalk. I mean this both technically and socially, regarding both the user and implementer communities.

Rebuild trust

All of this is very much my personal opinion, and not backed up by formal market research or anything similar.

OpenAPI has never truly produced a minor release. 2.0 came out in 2014, 3.0 in 2017, and 3.1 in 2021. 4.0 is planned for the end of 2024. All required massive amounts of work to support, which is part of why the releases are spaced 3-4 years apart. That is how long it has taken the ecosystem to catch up enough to even consider another major version.

While some in our community are really excited about Moonwalk, others are lamenting yet another big change that probably won't benefit them for quite a few years (although I am hoping we can do a variety of things to make Moonwalk easier to support and adopt).

The experience of the OpenAPI community has been one of multiple years of no visible movement, punctuated by massive changes that aren't broadly supported until the next massive change appears. Reading through the issue backlog, there's a lot of frustration at both the lack of interim progress and the fact that long adoption timelines mean that closing an issue as "resolved" doesn't mean it will be usable anytime soon.

3.2: the critical starting point

The most important thing about 3.2 is that it should be very easy to implement if you already support 3.1. It should deliver at least one exciting feature, and probably no more than three. It shouldn't break anything (aside from assumptions regarding ambiguous requirements, as discussed for patch releases.

• We want a release that vendors are happy to immediately support, that benefits a significant chunk of users.
• We want people who are investing, or considering investing in 3.1, to see that they will see additional benefits from the 3.x line while vendors catch up to Moonwalk.

With 3.2, smaller is better!

3.3+: converging with Moonwalk

With a successful 3.2, we can talk about a similarly-sized 3.3 without kicking up too much fear of another 3.1. By this time, Moonwalk should be increasingly clear We should consider "backporting" features that can fit into the 3.x syntax, much like Python 2.x minor releases tended to converge with 3.x releases for quite some time.

Obviously, a lot of Moonwalk can't be backported – the same was true of Python 3. But I suspect we will find some things that can. In terms of the basic semantics if not all of the details.

As with 3.2, any 3.x release should add at least one and probably no more than three features, to ensure that they can be implemented and used before the next 3.x+1 comes out.

Release cadence

Assuming we do multiple 3.x releases, the cadence should allow implementers who actively start working on a new 3.x release time to deploy the new support before piling on another minor release. Since these release should (as proper minor releases) be purely additive, it wouldn't be bad if they crowd up a bit- implementing 3.x+1 ought to mean you automatically can support 3.x (for x > 0).

[handrews]

Previous work assembling possible 3.x work items (many of which are now being addressed in Moonwalk) can be found at #2572

[lornajane]

I'm broadly in alignment with this (and hope others will chime in with their own views, aligned or otherwise!). Showing non-destructive and user-approachable progress in the 3.x family will be a supporting move for a successful community adoption of 4.x versions. I am in favour of evaluating and adopting improvements that:

• make the specification documents easier to understand, or make the specifics more clear, or link to resources that do either of those things. Making use of https://learn.openapis.org also means we can expand explanations and update examples without needing a formal spec update process.
• improve usability, even small gains (perhaps especially small gains!). There are some extensions "in the wild" that we could adopt into 3.1 - especially where they will be going in to Moonwalk in some form.
• are backwards-compatible, for example by adding optional fields. There are some great ideas in the issues list but if we have to support two versions of something, that's less compelling IMO.
• give an easier path to Moonwalk. Not all users will upgrade soon, but keeping that option as close to as many projects as possible seems like the right thing to do and will bear fruit (for our users more than anything!) over time.

[handrews]

I am proposing that we call the 3.2+ release series the Apollo Series, in reference to the Apollo Program that took incremental steps leading to the first humans walking on the Moon.

[EDIT: It turns out Apollo is associated with GraphQL. @baywet suggested Gemini, for the Gemini Program that preceded the Apollo program, which actually makes more sense as Apollo included the Moonwalk, and our Moonwalk release will not be part of 3.x. There have also been valid concerns raised about creating confusing amounts of jargon distracting from the actual work, in which case it might be best to just ship a 3.2 and let that speak for itself.]

Once we define a strategy for it [EDIT: or perhaps just once we ship the first concrete thing], we should write a blog post about it that is just as exuberant and broadly-promoted as the Moonwalk 2024 post.

(I am still working on organizing issues to suggest a 3.x road map)

[baywet]

Thanks for posting my initial suggestion. Gemini would make a lot of sense in our space oriented theme. However last week Google released google gemini and it might create confusion (similar to apollo and GraphQL).

We could move to the previous program Mercury, which were the baby steps for the human flights (life systems, safety systems, etc...) before Gemini started testing all other systems (flight, navigation, propulsion,...) which Apollo put together to get to the moon.

And if anyone coins Mercury before we make a decision, we should ask them for royalties.
Alternatively we can ignore Google because I really liked Gemini.

[lornajane]

I am proposing that we do not give pet names to our releases. It's confusing for people who interact with the project infrequently, and this is the group we most want to connect with. Names like that are fun to insiders (who have to say them all the time), but we're not the key group here. Let's figure out what goes in a patch release and name it in a way that people can understand how it relates to what they already have and know.