Open Community (TDC) Meeting, Thursday 17 October 2024

[github-actions]

Weekly meetings happen on Thursdays at 9am - 10am Pacific

This agenda gives visibility into discussion topics for the weekly Technical Developer Community (TDC) meetings. Sharing agenda items in advance allows people to plan to attend meetings where they have an interest in specific topics.

Whether attending or not, anyone can comment on this issue prior to the meeting to suggest topics or to add comments on planned topics or proposals.

Meetings take place over Zoom: https://zoom.us/j/975841675, dial-in passcode: 763054

Accessibility & Etiquette

• Participants must abide by our Code-of-Conduct.

• Meetings are recorded for future reference, and for those who are not able to attend in-person.

• We invite you to feel comfortable to challenge any language or behaviour that is harmful or not inclusive during this meeting.

• We look forward to your participation, but please consider these acts of etiquette:

  • Remain on mute when not speaking to prevent interruptions.
  • Blur your background to reduce visual distractions.
  • Use the Zoom meeting "Raise Hand" feature to notify the group when you wish to speak.

Blur My Background	Raise Hand

Agenda Structure

Topic	Owner	Decision/NextStep
Intros and governance meta-topics (5 mins)	TDC
Reports from Special Interest Groups (5 mins)	SIG members
Any other business (add comments below to suggest topics)	TDC
Approved spec PRs	@OAI/tsc
Active Projects	@OAI/openapi-maintainers
New issues needing attention	@OAI/triage

/cc @OAI/tsc please suggest items for inclusion.

[lornajane]

Review and voting for the Overlays spec. We need 6 @OAI/tsc votes which is essentially everyone. OAI/Overlay-Specification#69

PRs to review:

• Minor language fixes and simplification Overlay-Specification#79
• Align example section titles Overlay-Specification#78
• Added some MUSTs Overlay-Specification#77
• Updated use of URL to URI Overlay-Specification#76
• Edit pass of readme and spec Overlay-Specification#75

[ralfhandl]

OAS Patch Releases

• all PRs merged! 3.0.4 and 3.1.1 are ready to go! [edit by @handrews]
• Can we start the TSC voting period to release these?

Housekeeping

• Update ReSpec-rendered specification versions #4116

Meta-Schemas

• Run tests with YAML metaschemas #4137
• Workflow to publish schemas #4139

[jmertic]

Howdy! I'd love to join to connect around LFX usage, along with better understanding the governance structure and seeing how we could better document/streamline things.

[handrews]

@jmertic Thanks for making a pro-active suggestions here!

By "LFX" do you mean these tools? I'm having a bit of a hard time figuring out what is relevant given the many different purposes and audiences and... well, I'm a little lost. Would you be able to explain what tools might be most relevant to us right now? Is this more for the outreach/marketing team, the BGB, or the spec team(s), or all three?

Or is there a page that offers some info that's a little less marketing-ish and doesn't require creating an account to mess with things?

Personally, I am interested in the crowdfunding tools and how they would fit with our other funding strategies, although I don't know that that's really our top concern overall.

BTW, while you're welcome to reply here, if you just want to address this comment in the meeting that's fine with me, too. Again, thanks for initiating something here in the agenda issue!

[jmertic]

Good question @handrews! Yes LFX is a suite of tools, and often we fall into the trap of referring to them all collectively - sorry about that!

Specifically, I'd like to work on getting the project using our Project Control Center, specifically the committee and meeting management functions. More details at https://docs.linuxfoundation.org/lfx/project-control-center.

Over time, looking at LFX Insights will help measure contributions and community engagement, and perhaps LFX Mentorship could be a good tool around running mentorship programs to help engage students in the work. Both both are longer-term at this point, as we are more focused on getting things operationally consistent across our projects.

Let me know if this helps answer your questions more...

[handrews]

@jmertic that helps - thanks!

For meeting like this I don't see us moving off of GitHub+Zoom. If there's some other tool that tracks the meetings that's fine, but technical contributors shouldn't have to have an account on a new platform to see or join our calls.

Looking at the Insights checks for Standards, I'm concerned that placating this will divert attention away from other work. Our problems aren't that we don't know what's going on. Our problems are mostly around it being too hard to contribute, and throwing more metric requirements at us won't help that – I fear it would be quite the opposite.

I'm open to Insights being useful, but we have tons of work to do on the spec and the publication process and I don't want to slow any of that down any further to make a metrics platform happy. (Keep in mind that I'm not the decision-maker here, so this is just my personal opinion).

On the other hand, if LF can provide resources to get us lined up with Insights, then I have no objection. I'm just concerned about piling more work on the existing team.

[jmertic]

Hey @handrews - a few things, and ones we can cover during the TSC meeting as well...

• LFX PCC Meeting Management does not require an LF ID or any other login to join the meetings. This was the case a bit over a year ago, but based on community feedback that requirement was removed. All someone needs to provide is a name for public meetings ( but with an LF ID you get the benefit of faster meeting joining and access to a list of all of your LF meetings in one place ).
• You can still use GitHub for meeting organizationg ( agendas, notes, etc ). In fact - most of the projects I work with do just that and it works quite well.
• The legwork for Insights is something the LF staff can drive. It would be good to think about metrics you'd like to have more visibility into, but that is something that should be discussed within the TSC first.
• Regarding contributor experience - I'd love to dig more into that with this group, understanding the current experience and the challenges being seen.

Hopefully this helps!

[handrews]

Thanks, @jmertic ! This is all very helpful. A few further thoughts:

LFX PCC Meeting Management does not require an LF ID or any other login to join the meetings. This was the case a bit over a year ago, but based on community feedback that requirement was removed.

It's really great to hear that this sort of feedback has been incorporated! It makes me more interested in using the LFX suite.

The legwork for Insights is something the LF staff can drive. It would be good to think about metrics you'd like to have more visibility into, but that is something that should be discussed within the TSC first.

Yeah, agreed. My main concern is to avoid doing things that don't fit our project just because Insights has some metric tracking it. I've seen metrics programs go off the rails that way (I've also seen metrics be very helpful).

Regarding contributor experience - I'd love to dig more into that with this group, understanding the current experience and the challenges being seen.

The below is my personal opinion only:

We lost some institutional knowledge when the project went into semi-hibernation after 3.1 through the pandemic until 2023ish. Re-building it is hard (but we're making progress) and documenting it is harder (we're struggling the most with this).

We actually gave up on our old docs and started trying to build new docs alongside of them. If you know any technical writers who would like to burnish their open source credentials, we desperately need people who can write up the processes we know, and help us figure out what we need to document properly.

We'll probably talk about the difficulties with contributing to schemas in this meeting, which will thoroughly illustrate the problem. PR #4132 shows a contributor who has been around the project for years running into all sorts of undocumented road blocks.

With some of this, we know what we need to do, and it's just a question of doing it. Other things are, I think, less clear.

[jmertic]

Thanks for the context, @handrews.

I am not sure if the group has looked at the Community Specification License ( https://github.com/CommunitySpecification/Community_Specification ); I only mention it as some of the docs you reference are very policy-focused, so it might make sense to align with an existing license/structure that has some sensible defaults for the nuances and goes into further details on areas the group might not have thought of. I am happy to dig into this more with the group and bring in our LF experts, who can discuss this further.

[handrews]

@jmertic I took at look at the Community Specification stuff, and (without commenting on its general quality or suitableness for new projects), it doesn't seem to be addressing the areas that are problematic for us. I think we actually do fine on the overarching governance, licensing, etc. (others may disagree- TBH I don't have the greatest visibility on that)

Our problems are lower-level. For the schemas: How strict should they be? What branch are they developed on? Published from? Should PRs target YAML, JSON, or both? Why do we have out-of-date JSON files checked in? etc. etc. There are some similar questions for the specs, although most of those are in the "we know what to do, we just need to do it" state.

These aren't things the LF can or should answer for us directly (although the Community Specifications have good guidelines about things like organizing repos, which match the infrastructure changes we're already planning to make).

Migrating to the Community Specification framework would introduce a lot of work to figure out where we differ and what to do about it. That's exactly the kind of work that I, personally, do not want to add to the exceedingly long queue. Or we could put it there, but it would be a couple hundred issues down in priority (again, for me - others may differ).

[jmertic]

Hey, @handrews, those are all fair points. Separating the tactical vs. governance questions and getting everything outlined would do wonders here. I view the CSL as a solid, known base for governance, which lets the community work out the details of the process. Both can be separate streams, and at least the CSL bits aren't highly urgent ( though something worth spending some cycles on to understand the context ).

We can certainly help with the tactical aspect from our experiences working with other communities.

[handrews]

@jmertic yeah investigating how the CSL could fit us seems more non-urgent-strategic, while the other issues are very urgent-tactical. My view is that the tactical issues that we need to resolve to get us to an OAS 3.2 release with infrastructure that properly supports us having multiple specifications with multiple release lines, with clear contributor guidance, are the priority for now. And yes, if there is someone who is available to look at CSL, that can happen at the same time in the background.

[FelixHarvey]

Meetings are recorded for future reference

I noticed that the links to Zoom recordings are quite sporadic across the meeting issues and was wondering if they are linked in a centralised spot? I'm keen to hear the discussion but unfortunately 9am Pacific is 3am in my local time so attending live is a bit impractical.

[handrews]

@FelixHarvey they should get linked in these issues- it seems that this has not been consistent for the Thursday meetings, so we should discuss that in the call and make sure someone is on that (I'm not actually sure who has direct access to the recordings). This is something that, I think, the LFX meeting tools that @jmertic mentioned above would help us with, so perhaps we'll have a more reliable solution soon.

[handrews]

@jmertic one thing that would probably be very helpful tactically is any assistance in getting community review of the proposed 3.2 release (once it's far enough along to be coherent, which shouldn't take too long once 3.0.4 and 3.1.1 are out).

The goal of 3.2 is to re-establish trust by making a small, easily-supported, fully-compatible-with-3.1 incremental step towards Moonwalk. This will only work if implementors agree that it's easily-supported and worth supporting. My biggest worry about 3.2 is that we will guess wrong and won't be able to get enough of the right eyes on it before release.

[jmertic]

@handrews If it's appropriate, it would be great to discuss during the TSC meeting today.

[jmertic]

Also, I'd like to add to the agenda the creation of a repo in this GH org for hosting a landscape ( see https://github.com/cncf/landscape2 ). The initial scope would be to automate our membership logo display ( for example at https://www.openapis.org/membership/members ), but over time, the TSC can look at other ways to showcase the ecosystem.

[lornajane]

I'll try to recap the contents of the meeting from my notes, please add more comments if there's things you think we should mention for people who missed it!

@jmertic is our interim Linux Foundation rep and joined the meeting for the first time to introduce himself and tell us about tools and ask us about our Governance structures. @handrews and @earth2marsh will fill in the details on the governance structure and we'll share the outputs with this meeting when we have them. We also talked about the LFX meetings platform, our past issues with it and reasons to retry it. We agreed that the Moonwalk meeting would like to be the test cohort for the new tools, before we update our largest and most public meeting's logistics.

The Overlays specification 1.0.0 release vote was re-opened and approved by all 6 TSC members present (and plenty of very well qualified bystanders on the call too) - the release will be cut "soon".

On a roll with specification releases, we proceeded to agree to open the votes for the patch releases on the main OpenAPI 3.x specification, these will be #4080 and #4082 - the vote will be officially open for three days and need 5 approvals from @OAI/tsc to pass. As per our process, announcements of the vote were posted in the slack channel.

NOTE when the pull requests mentioned above are merged, ensure that the contents are not squashed, this will make it very difficult to understand the context of individual changes in future.

After the patch releases are cut, there are some project structure changes planned. These include:

• restructuring the working file and git branches. Details to follow, but tentatively we expect to a branch per version (3.1, 3.2) that we release patches from, and the specification itself is in a file named src/oas.md on every branch.
• there are open pull requests to remove the examples folders, we can revisit these after publishing (because the new links point to the new examples locations)

We also discussed that the schemas are a weak spot. We have not previously committed to publishing schemas for the specification formats, but it seems like these are widely expected and used by many. With more schema expertise available in the group now, we are ready to review the schemas, accept and review changes, improve the tooling, and make sure they get published and shared as official resources once they are ready.

It was a packed meeting, a week of good news, thanks everyone for your patience and contributions!