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.