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.

[handrews]

@lornajane the only reason I proposed a code name is that I've heard from several people that they are frustrated with the apparent focus on Moonwalk, and feel that incremental improvements to the 3.x line, where people are actually using the spec right now, is being neglected.

My thought was that since we made a code name for Moonwalk and a big splashy blog post about it, that we could reassure people that we're taking 3.x just as seriously by doing the exact same thing for it.

But my main goal is to reassure 3.x users. I don't feel strongly about the code name as long as we do some PR (public relations, not pull request) to counter the growing (as far as I can tell from a small bit of anecdotal evidence) sense that the OpenAPI Project is too detached from its active user and implementor base.

I'm in favor of anything that accomplishes that goal. The only concern I have about waiting until we define some patch and minor releases is that it's likely to take another month or two, and we could raise awareness and interest (and maybe get more input into the process) by promoting 3.x in some way earlier. That also does not require a code name.

But ideally it would involve defining some guiding principles for 3.x, as the list of principles have been very helpful reference points for Moonwalk discussions. And I am not the only person who has been pointing to them.
I was trying to think of some principles a while back and this was what I came up with (not intended to be a final proposal, but I haven't gotten back to it so I might as well post what I have):

---

Principles for Users

• Seamless upgrade experience
• Minor releases that add enough to motivate upgrading
• An easier upgrade to Moonwalk for those who keep current with 3.2+

Principles for Developers

• One codebase for 3.1 and all later 3.x releases
• Align the pace of minor release publication and implementation
• Features backported from Moonwalk will try to allow sharing code between 3.x and 4.x

[lornajane]

Splashy blog post would be fine by me, and I don't think a month or two wait is a problem. Let's get some good release notes out when we do those releases and I think that's going to go a long way.

[handrews]

@lornajane If it's only a month or two, I agree it really doesn't matter. I'm actually not sure why I used that phrase, as I'm a bit skeptical that we'll put anything out in that time frame. But I'm plenty willing to wait and see for a couple of months.

[handrews]

Discussion from TDC call 18 Apr 2024:

• Minor releases (or at least 3.2) will be primarily collections of community-driven contributions
• @darrelmiller notes that we need to avoid burdening tool implementers with too many niche features
  • "niche" is @handrews 's term for this, meaning features where the ratio of implementation effort to deployed usage or demand is a bit questionable
  • @handrews suggests that certain niche features could be designated "SHOULD" requirements, although we need to be aware of the interoperability costs of relaxing requirements in that way – interoperability is the entire point of having a spec, after all
• @handrews emphasized closing and shipping the release before too many features (niche or otherwise) accumulate, as we want more frequent, small, and easily implemented releases (see prior discussion in this issue)
• @handrews also notes that if we feel the release is filling up but lacks a marquee feature, we should pick one marquee feature that the TSC agrees will make for a good announcement, get that feature in, and then ship; this is intended as a compromise between "ship whatever shows up" and "fully plan a coherent release"