Should we put out a 3.0.5 (or formal Errata for 3.0.4)?

[handrews]

For good reasons, we declared that we would not do a 3.0.5 release.

However, we have discovered some outright errors in the 3.0.4 text, most notably the guidance around percent-encoding and in: header, and to a more ambiguous degree around multipart. It would not be hard to backport these (and whatever other few trivial-to-backport 3.1.2 fixes, as there are really not that many) and do a 3.0.5. Or we could do something novel and issue errata.

3.0.5 option

We could do a quick 3.0.5, either by manually constructing the document out of the published 3.0.4 spec using something akin to our old process of patching different files across branches (I still have a somewhat quirky script I can use for this), or by making a v3.0-dev branch.

Pros:

• It's what people will expect
• It would be the same publication process we know

Cons:

• It's annoying work
• We said we wouldn't do it

Errata option

We could edit 3.0.4 in-place to add "Errata" links (ideally at the top of each section with errors) to something hosted on the spec site. Note that this is what IETF does, and we usually cite IETF as the precedent for not updating in place, so this sort of update-in-place should be fine. (idk if W3C does this or not)

Pros:

• We don't need to resurrect a branch

Cons:

• No one will expect it or know to look for it
• No one reads the top-level intro part, so we'd need to put more Errata links than an IETF RFC does
• We'll still need to do annoying infrastructure work

Tagging @OAI/tsc

[lornajane]

You forgot the "do nothing" option

[ralfhandl]

"Do nothing" is tempting, but we do have a broken link for "Security Scheme Object" in 3.0.4 - links go to the fixed field in the Components Object instead of the section on "Security Scheme Object".

Fixing this would not change visible text and only repair the anchor(s), so we could argue to do that in-place.

[karenetheridge]

My doesn't-really-count-for-anything vote would be for doing a 3.0.5, and using this as an opportunity to streamline the release process (and who knows, there could be a need for a 3.0.6 at some point).

[karenetheridge]

If doing a 3.0.5 releases is easier then putting up errata, let's do that! There should be no embarrassment in doing more point releases. IMO it shows that we're paying attention to this version series still.

[handrews]

@karenetheridge thinking further on this, the errata would not be harder and might even be easier, as long as no one objects to putting links in the appropriate sections of 3.0.4 on main. For some reason I was thinking we'd still need a release branch for errata, but we would not.

[ralfhandl]

Personally I prefer full up-to-date specification documents over outdated specs with separate errata.

When I look up some arcane detail a specification document, I may simply forget to scan the errata for something that applies to the sections I just re-read.

[ralfhandl]

Technically we can add an errata link in ReSpec which appears between "Former Editors" and "Other Versions":

Apparently we can't change the text "Errata exists.".

Drawbacks (in addition to the hassle of a separate errata document):

• It's easy to overlook, see https://ralfhandl.github.io/respec-experiments/.
• One of us has to fiddle with the md2html build script to get that link in.

[lornajane]

I'm sorry for replying flippantly from my phone about "do nothing". It's more than just lazy inaction in this case. We've clearly said that we're done with 3.0, 3.1 is not exactly new and 3.2 really is better in both quality of life and new features. We've got our eyes on Moonwalk and the possibilities there, there needs to be a clear message that there is such a thing as a version that is "not Okay". We aren't offering updates to 2.0 and at the time we released 3.1 that still had a decent size of usage.

Nobody should be reading the 3.0 specification today for implementation - most of the tools from that era are already obsolete and no further development is likely for the ones that do still work. The headline will reach a lot of people but the actual content of the change probably won't. I am well aligned with the principles that drive this suggestion, but I consider it a strategic misstep from a bigger-picture perspective. Sorry.

[karenetheridge]

Nobody should be reading the 3.0 specification today for implementation

Speaking of which... is it easy to put a banner at the top of that page that says as much? Or if it is, instead say the equivalent on the main page that lists all the spec versions? Given that semver is prevalent, the naive user might think that 3.0 is "close enough" and that 3.1 is just an incremental change on top of that.

[ralfhandl]

Nobody should be reading the 3.0 specification today for implementation

is it easy to put a banner at the top of that page that says as much?

I can't find a corresponding ReSpec configuration option.

We already have a prominent link to the latest published version on the title page:

[lornajane]

I agree that we should make it easier that this version is end of life and should not be actively used. I wouldn't advocate for removing any resources however.

[ralfhandl]

From a user perspective 3.0 is definitely not end-of-life, it is in fact the go-to version for many hundreds of our OADs that still use 2.0.

We are planning to allow using 3.1 really soon now, probably already next year.

End-of-use for 3.0 may be end of next decade, if things move really fast.

So I strongly object to declaring end-of-life for 3.0 this decade 😎

Which is why I think that a 3.0.5 release that cleans up for example URI resolution is preferable to errata and to "do nothing".

[handrews]

@OAI/tsc I would like a formal decision on this, please. @lornajane and I both feel very strongly about our positions, and I do not think it is beneficial to either the project or our personal stress levels for us to go around and around here when our arguments are both, to my view, well-reasoned and supported by different perspectives rather than an objectively clear principle.

The reason to consider action is that the current text of 3.0.4 (and 3.1.1) advises tooling vendors to implement the wrong behavior, which will complicate the upgrade path to the releases that we want people to be using. Acting to mitigate this situation is not about extending the life of 3.0, it is about ensuring that those on 3.0 do not get stuck with further incompatibilities making it harder for them to upgrade.

I will note that there is also a minor schema omission that could be fixed (#3720), but as it does not prevent correct OADs from validating, I will not focus on it. The erroneous text in 3.0.4, however, prevents correct OAD behavior.

Options:

1. Make a 3.0.5. This would match how we handled things for 3.1.2. It would require a v3.0-dev branch to be set up.
2. Add errata, with a link in each section that has errors (because the spec is too big to just have one up at the top, and as @ralfhandl noted, there is no standard place for such things in ReSpec, unlike the IETF format which does have a place people know to check for errata). This could be fixed on main, as it is directly analogous to how the IETF updates RFCs in-place to add "Errata Exists" (which is, AFAIK, the only way in which IETF RFCs are updated in-place). The errata itself could be a blog post or a page on spec.openapis.org. A nice feature of this option is that we could use it in the future between releases, a possibility which has come up before. We could also make similar errata links in 3.1.1 pointing to the same errata.
3. Do nothing. Tooling vendors checking 3.0.4 for new guidance would implement the wrong behavior, contradicting anything implemented based on 3.1.2 or 3.2.0 and complicating the upgrade path.

The idea of errata for the OAS is not new. It has come up several times as problematic errors have been found between releases. Adding the errata to both 3.0.4 and 3.1.1 would help position this as not a prolonging of the 3.0 line, but as a general tidying-up of our history as a UX improvement for our implementors and users. The position of he errata links near the actual errors (the details of which would no doubt require a bit of finagling) would support doing this quietly rather than with the fanfare that a 3.0.5 would involve, as we are only concerned with people who are actually looking at 3.0.4. I agree that such fanfare is not desirable.

Errata links are a standard way to handle this, particularly in the IETF. They are done in the IETF whether there is an intent to ever publish a version incorporating the errata or not. It seems like a good compromise to avoid the public perception that 3.0 is still an active release line while ensuring that the many people still working on 3.0 have some way to avoid doing the wrong thing and expecting the wrong behavior. Documenting the correction is the best way to ensure the best UX for updating from 3.0 to 3.1 and 3.2.

[lornajane]

We have clearly stated that 3.0 is end of life and no longer maintained. We serve our user and contributor communities best when we follow our own messaging and help them to continue to evolve and make good use of the supported versions in a reasonable timescale. It also means we make respectful use of volunteer efforts by not cultivating an expectation that we will maintain several versions of OpenAPI concurrently. This proposal is well-intentioned but overlooks the wider project context.

[karenetheridge]

@lornajane Does your latest response indicate a support for adding errata notes to 3.0.4, or is it towards doing nothing?

[lornajane]

I strongly advocate that we do nothing

[handrews]

@lornajane and this is why I'm calling for a vote and a formal decision. Neither of us are going to budge on this, because we're both arguing from well-defined but different perspectives. There's no objectively correct answer here, the TSC just has to make a decision.

[lornajane]

I'm sorry if you feel that I'm speaking out of turn again, I was replying to a direct question about my position. We are also discussing in TSC.

[handrews]

@lornajane oh goodness, no! I am terribly sorry that it came across that way. I meant to tag @karenetheridge as a "yeah this is why I asked for this, which may not have been clear" and accidentally tagged you instead on autopilot as the last comment 🤦

[mikekistler]

Is there any recent data on adoption of v3.1 over v3.0? The 2023 Postman survey still showed a surprising number of users (the majority in fact) still using v2.0 over v3.x.

I think @lornajane makes an import point:

It also means we make respectful use of volunteer efforts

It is hard enough to just make progress on the newer versions of the spec. But at the same time, if there are volunteers that want to update v3.0.x -- backporting clarifications and such from later releases -- maybe because their company or application is still using v3.0.x and getting value from it, I'm not sure we should reject these volunteer's effforts either.

[handrews]

@mikekistler to be clear, I would volunteer to do the editing for a 3.0.5 if doing so were TSC-approved, and @ralfhandl already submitted a PR to create the necessary branch. I need a break from trying to advocate new features anyway. I think the only practical implication of that is that we shouldn't decline to do a 3.0.5 just from concern over having someone available to do it. But that is not main objection, the main objection has more to do with user/market perception and adoption.

One position is that showing any 3.0 activity is counter-productive, and the other is that making sure the end of the 3.0 line is healthy will support migration than leaving the end of the 3.0 line in a confusing and contradictory state.

[handrews]

@mikekistler also there has definitely been more recent info that shows 3.x overtaking 2.0, although 3.0 is still much bigger than 3.1. IIRC, 3.0 alone was smaller than 2.0, but 3.0 + 3.1 was larger. I can't find the report right now, although it was discussed on the Slack quite a bit at the time. I also know that a vendor who works mostly with companies building new APIs was seeing about even 3.0 vs 3.1 maybe two years ago? And I think trending more and more towards 3.1. So it's not that new APIs are going into 2.0, it's just that there are a lot of old APIs, and some companies no longer really update their technology.