3.x.y patch release approach

[handrews]

We plan to release at least 3.0.4 and 3.1.1, and likely more 3.1.x releases. We need to figure out what goes in and when to call these releases "done."

Goal and Scope

The overarching goal of all 3.x(.y) release should be smoothing the path to Moonwalk. This has two components:

• Clarify ambiguities and omissions to make migration more predictable
• Reduce the guesswork involved in reaching full compliance with the spec for various use cases

Doing these things should increase satisfaction with the 3.x line as well.

We have a solid precedent for clarifying omissions or ambiguities from 3.0.3, which further specified nullable's behavior to smooth the path to 3.1's full JSON Schema support:

• Add proposal to clarify nullable #2050
• Resolved undocumented nullable behavior #2046

This change technically invalidated assumptions that some implementations made, but did not invalidate any clear normative requirement.

We should also use normative language (MUST, SHOULD, MAY, etc.) wherever possible to make compliance requirements clear. These requirements will need to map to Moonwalk, and ideally all compliance requirements could be tied to such language. That's probably not realistic, but we can get closer.

Definition of done

The main question here is whether 3.0.4 is the last 3.0.y or whether we can continue patching it. If 3.0.4 is the last, then we want to get as many clarifications into it as possible (and 3.1.1 should go out with it, I think).

If we're OK doing more 3.0.y releases alongside 3.1.y releases, then we can pretty much ship a patch release whenever we think there's something worth shipping. A more-or-less quarterly cadence is probably realistic [EDIT: that's probably more frequent than necessary] (at least once we solve our release process roadblocks).

I personally don't see the need to end the 3.0.y line. It and the 3.1.y line are close enough that most patches will apply to both. It would be a minimal effort to make 3.0 customers feel supported.

[handrews]

Another area for patch releases is improving examples within the spec, or adding links to the Learn site if we want to avoid taking up too much space in the spec itself.

[lornajane]

I'd suggest that we say that features are to be added on 3.1 branches only, but let's keep adding resources, clarifications and upgrade-easing changes to both 3.0 and 3.1. We do have users on 3.0 that we expect to make the 4.0 upgrade some day, but now that 3.1 has widespread tooling support I think we can expect that projects looking for new additions are on 3.1 (and we should encourage that).

[LasneF]

i would not stop improving the documentation and so not close any version .
especially following the semantic versionning and the micro version upgrade . here it is about updating , clarifying the documentation , and sample without adding any new feature .

then the definition of done should be a mixte of :

• is the bag is content is big enough : definition of big could be either a lot of small clarification, eihter a single but important clarification
• is the current revision very old. And so releasing on a cadence 1 quarter, or even 1 semester could be enough

then given this fact this may includes that it requires to open a dedicated branch -dev for 3.1.0-dev , that by the way could be confusing toward having 3.0-dev , 3.1-dev , 3.2-dev and may 2.0-dev (2.0 could be set as deprecated and so no maintenance)

and also create a 4.0-dev for moonwalk ...

also one point to consider is the backport of precision , to me should not have automatic rules here especially if it is painfull
should be done as best effort

[handrews]

@LasneF I pretty much agree with your definition of done. As much as I'd like quarterly patch releases, I doubt we can move that fast yet (I may be pleasantly surprised).

I think the current branching approach is fine- having to pick the right branch helps guide people to pick the matching file, and we're already changing a lot of other things. I've submitted a PR with a PR template to guide folks to the right branch/file. We definitely won't be doing more on 2.0.

I agree with the pain around backporting, which is why I'm a strong supporter of committing to the oldest relevant release and forward-porting. It's almost always obvious whether something can or should be forward-ported. I'm indifferent as to whether it's automated or manual as long as if it is manual there are clear lines of responsibility.

[handrews]

As I've audited the backlog and labels we are using, I've added two labels that highlight work suitable patch releases:

• bugs [Note: added in a later edit]
• clarification
  • 45 open issues as of this writing
  • work that (in theory) does not change any requirements beyond what a patch release can accommodate
  • patch releases might require informal recommendations which can be elevated to SHOULDs in a minor release
  • some of this work may be better routed to the learn repository, as the spec should only include the guidance needed to implement correctly
• examples
  • 28 open issues as of this writing
  • improving and expanding examples
  • (not to be confused with the example obj/keywords label)
  • most of this can probably move to the learn repository, but some should stay in the spec
  • often great opportunities for new contributors

Certain feature areas are particularly well-represented in the above categories:

• Media Types and Encoding: 10 clarifications, 1 example
• Parameter and Header Serialization: 8 clarifications, 5 examples
• Request Matching: 6 clarifications, 1 example
• Discriminator: 4 clarifications, 1 example

Some of the above categories overlap. There are also quite a few clarifications and examples that don't fit any major functionality bucket that I've identified so far.

I will be updating #3529 (minor release approach) in the next week-ish to propose some possible minor release themes. The volume of tickets is similar, except that there are a lot more security and re-use issues that can only go in a minor or major release.

It would be good to pick the same areas of focus for our first set of patch and minor releases. Today in the Moonwalk meeting we also discussed the possibility of prioritizing deployment and security there, and making more incremental progress on the shape side [NOTE: I just floated this idea, it's not even close to an agreed-to plan]. All of the above feature areas are shape-side features, and making solid progress in some or all of them would be great, and could support similarly-focused minor releases.

Clarifications in referencing might also be relevant, but there's a bigger picture there that needs sorting out so it may not be quite ready.

I think at this point we just need to:

1. sort out the minor release plan so we can put together a coherent road map
2. see if anyone thinks the above is really missing something we should address as a theme (we can always include individual fixes that people feel strongly about, so don't worry if your favorite issue is not in the theme list)

[miqui]

I'd suggest that we say that features are to be added on 3.1 branches only, but let's keep adding resources, clarifications and upgrade-easing changes to both 3.0 and 3.1. We do have users on 3.0 that we expect to make the 4.0 upgrade some day, but now that 3.1 has widespread tooling support I think we can expect that projects looking for new additions are on 3.1 (and we should encourage that).

@lornajane , @handrews - I agree with this point, but do we have enough bandwidth to maintain a 3.0.x and a 3.1.y? (or, this is ok for slower than a quarterly rate?)
I hope most issues/clarifications can be easily ported to 3.1. What happens when we introduce a 3.2.x line? Simply stop the 3.0.x line?

[handrews]

@miqui As the strike-through text and following note indicates, I don't think we'll manage quarterly. I'll be thrilled at twice a year.

Doing both 3.0.y and 3.1.y is quite easy - changes that apply to both go into 3.0.4 and get forward-ported (there's a script that can do this), and changes that only apply to 3.1 go into 3.1.1. This is much easier than just putting things in 3.1.1 and then trying to figure out what goes into 3.0.4. I'm doing that right now and will submit a PR on 3.0.4 to bring the lines into parity very soon.

In terms of thought-effort, it's trivial unless someone finds a major 3.0-only clarification. And we can decide whether that's worthwhile or not when if and we get there. (TBH, the most likely place is with weird content encodings, and I'll have to do that part as I messed it up to begin with, and I'm not bothered by doing both - everything else in the above list is pretty similar between the two release lines).

Both get forward-ported to 3.2 as relevant, although I expect that to diverge more. But we'll decide on that when we plan the minor releases.

[handrews]

We should also fix the few actual bugs in the spec.

[handrews]

In a recent TDC call, @ralfhandl brought up that the "clarification" of nullable in 3.0.3, despite resolving an ambiguity, was a de-facto breaking change for him with significant impact.

This emphasizes that we should be careful in patch releases to use the right wording to make the clarifications non-breaking. Specifically:

• do we use SHOULD or is that too much of a requirement elevation for a patch release? Disregarding a SHOULD does not result in non-compliance
• if not a SHOULD, do we use informal language, or is there a usage of MAY that makes sense?
• if using informal language, do we want to pick some consistent language for in-spec guidance to avoid having to debate it repeatedly? 😅

[baywet]

Joining the discussion here a bit late, but to recap some of the things I've said on the call: I think we should consider the specification like a product, and define and document a support/maintenance lifecycle policy.
A little like the dotnet framework does as a example, of course that ties into the release schedule which we haven't defined either, but we could start defining the former, and adjust later on.

Doing so would help:

• reduce maintenance burden
• accelerate triage of issues
• define branching and tooling strategies
• clarify expectations for consumer of the specification

At a high level I'd define such policy like this:

• The date a new major version releases, the previous major will only be supported for up to 1 year, and only for bugfixes (typos, broken links, etc...). (if v4 releases on June 2024, we'll only even produce minors and patches for 3.X up until June 2025)
• The date a new minor version releases, the previous minor version will only be supported for up to 3 months. (3.2 comes out in May 2024 3.1 will only get new patches until August 2025)
• The date a new minor version, the previous version is not supported anymore (3.1.2 comes out next week, no more updates to 3.1.1 moving forward)
• Any updates to existing specification versions will be done through increasing the major/minor/patch version depending on the kind of update. This serves to both trigger the support countdown and signal changes to implementers/users they should consider. We should never update a specification in place except for major bugs (broken links etc...) as @lornajane said during the meeting.

Thoughts?

[baywet]

We can debate the timelines etc... But applying that policy now that would mean only those versions are supported today:

• 3.1.1 is in ongoing support, until either 3.1.2 or 3.2.0 come out, and will be updated only for bugs in place, or through a new version for anything else.
• 3.0.3 is in ongoing support, which will end when 3.0.4 comes out. And 3.0.4 will be immediately out of support since 3.1 has already been out for other 3 months, and will be the last version as @lornajane suggested. This is kind of a grandparent clause at this point as we normalize the support policy.
• 2.X/1.X are entirely out of support

[lornajane]

@baywet This is the full project release history - Your ideas are good but they are entirely the wrong "size" for a project like this which took ten years to release a number of times that I can fit on a post-it note. The last project release was literal years ago.

As an open specification, I'm not sure what you mean when you say "support". We publish a version, and people can use that document. It's not code, so I'm tempted to say that the software project comparisons are not that useful. Nor would we refuse to "support" in the sense of answering questions because an arbitrary date had passed (although we mostly work on the newest versions so the old knowledge does fade!)

[lornajane]

My comments from today's meeting, copied here as it's probably a better place for them:

Released spec versions are immutable. Even for broken links. Let's get better at releasing patches as needed. This approach also stops all the discussion about editing tags. Technically possible or not, it's probably a bad idea. New versions are always safe and we should do that.
We currently maintain 3.0 and 3.1 branches. Our next set of releases will include a 3.2.0, and I propose that we therefore declare 3.0.4 as the final 3.0.x release and move to maintaining 3.1 and 3.2 instead. This is in line with the direction of travel of the project and will reduce the workload/complexity of what goes on which branch. There's nothing stopping us from doing a quick 3.0.5 if something compelling came up in the future.

Many OpenAPI users are on 3.0.x, but neither their API descriptions nor their tooling tracks new OpenAPI 3.0.x releases, so there's limited benefit to this work (I mostly see 3.0.1 versions, not sure why). We want to be moving forward and offering reasons to upgrade, so people can keep using what they know, and the 3.1 ecosystem is mature enough for people to upgrade without feeling like they're at the bleeding edge.

[baywet]

When I say "support" I mean "make changes to a release for the purpose of maintaining it or improving the quality of life".

I thought the point of Gemini/Mecury/whatever we call it was to produce more frequent minor and patch releases to avoid a big-bang approach with moonwalk? With that context in mind, wouldn't we want to avoid a sprawl of versions we need to maintain and clarify for how long anything will get maintenance/support?

While I agree with the "3.0.4" version will be the final one for 3.0, it's seems like an arbitrary decision rather than an planned for lifecycle aspect. This is why I believe we should formalize things moving forward.

Assuming we take the immutable aspect to the letter, which I also agree is a great thing to do to avoid confusion but might be painful for things like broken links etc... The policy as I defined it at a high-level still holds, the examples though can be updated to:

• 3.1.1 is in ongoing support, until either 3.1.2 or 3.2.0 come out, and will be updated only for bugs in place, or through a new patch version.
• 3.0.3 is in ongoing support, which will end when 3.0.4 comes out. And 3.0.4 will be immediately out of support since 3.1 has already been out for over 3 months, and will be the last version. This is a special grandparent clause because the work here is already mostly done.
• 2.X/1.X are entirely out of support, no new patches/minors to be expected.

[handrews]

We seem to have disagreement about what goes in a patch release. My understanding is that only non-breaking bugfixes and clarifications (so no more clarifications like nullable in 3.0.3). But in #3595 @lornajane suggested allowing adding optional fields.

We need to decide what is allowed in a patch release even more urgently than deciding what to put in any specific release.

[handrews]

@lornajane I believe we decided in this week's TDC meeting to keep the more strict "non-breaking bugfixes and clarifications only" policy for patch releases. Am I remembering this correctly?

[lornajane]

Yes, we had a discussion about being cautious in patch releases and putting everything new into minor (or major!) releases so that users and toolmakers alike know exactly what's expected on both sides. Let's formalise the distinction as briefly as we can, and then use it for reference on our upcoming releases!