Open Community (TDC) Meeting, Thursday 21 March 2024 about openapi-specification

[lornajane]

A few points from my notes/memory:

@earth2marsh announced provisional new membership of the TSC this week. Alongside #3669 which expands some of our existing project governance, the newest provisional members are @ralfhandl @mikekistler, @miqui and @lornajane

We talked about our general enthusiasm for getting better OAuth2 examples and, where needed, additional support in the specification to support OAuth2 as it evolves. This includes #3612 for DPoP and #3625 for the metadata URL field - but also support for missing flows like token exchange and device code flow.

We also talked about our git versioning/branching/development workflow and it's clear that we are in need of a change. A fruitful discussion seems to have happened this week in the Moonwalk SIG meeting. A high-level summary of what I understood would be:

• there is one file in the repository called oas.md and this is the canonical spec version (so I guess on main it's the latest stable release? We didn't talk about that)
• we maintain one branch for 3.0, where oas.md is under active development and will become the 3.0.4 release. The branch will be tagged at release time. The same pattern for a 3.1 branch where the next tag would be 3.1.1 and a 3.2 branch where we'll tag 3.2.0.
• when we tag a new version, we also copy the oas.md into the main branch under the versions structure that we have now.

The advantages of this structure are that we can diff the different versions and revisions of the same file in a sane way. There are fewer branches to keep track of so things should be easier to reason about. And it gives a simpler workflow for adding versions (hello 4.0) as we move forward.

My questions: where are we having the discussion about this that isn't in an agenda comment thread? And how do we apply changes such as tooling updates to the minor version branches without affecting the oas.md file? /cc @miqui since I know you're putting something together on this.

As a followup to getting the branches sorted, at some point we can change our use of github pages - currently it uses a branch, which was a very early implementation. We think it would be more useful to use a subfolder now.

[handrews]

• #3669
• #3626
• #3629
  • #3671
  • #3553
  • #3539
• #3527 (comment)
  • #2386

Security PRs (I haven't looked at these recently, just figured I'd highlight the cluster of security stuff):

• #3613
• #3615
• #3622 (one approval from @lornajane )
• #3625
• #3632

[earth2marsh]

Let's cover #3669 today, too.

[handrews]

@lornajane I filed #3677 for the branching discussion. I almost filed a Discussion discussion but I wanted to put it in the Automation & Infrastructure project and you can't put discussions in projects. Plus this is pretty close to actionable.