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: