Use community repo for governance, info, & user/dev help questions

[handrews]

[NOTE: I'm filing this issue in this repo because it's about things that currently happen here.]

In today's call we rediscovered the OAI/community repository.

• It has a lot of useful information, but some of it is out of date, and there's significant overlap with things in this repository.
• It would be the ideal place to route user / implementor questions that are a huge percentage of the issues and discussions here in the spec repo (@lornajane kind of like our discussion of moving them to the learn repo, but even better because then we can just use learn issues for actual docs changes)
• It seems like a better home for our general governance and process work. Perhaps the Process label can move over there, and we keep Housekeeping here for the day-to-day repo/project specific stuff? (paging @earth2marsh from our Process vs Housekeeping discussion)

Note that @webron transferred OAI/community#5 over to that repo as a community question, so apparently we already thought about doing that part once.

Proposed workflow for user / implementor questions

Currently we have two places (issues and discussions in this repo) serving three purposes:

• open-ended discussions (ideal for discussions, but historically mostly in issues
• actionable tasks (ideal for issues, but sometimes end up in discussions where they're even less likely to get a response)
• community members asking for help (probably the largest usage of both issues and discussions)

This makes the @OAI/triage work complex because community member questions aren't necessarily related to spec development, but could lead to changes so we tend to keep them open indefinitely. But it's very hard to extract what changes are needed, if any, from long back-and-forths that are more help-desk-like than spec writing.

• When a user question issue or discussion is opened in any repo other than OAI/community, @OAI/triage immediately transfers it to OAI/community, before responding at all
• If something in OAI/community turns out to motivate a spec change, open a new issue (if the change is clear) or discussion (if it's a broad topic that needs more discussion) in this repo (or the appropriate SIG repo), and link to the OAI/commuity issue
• If something in OAI/community motivates documentation or examples on the Learn site, either open a new issue or move the issue over to OAI/learn.openapis.org
• I'd still argue for closing answered questions, but if we want that

We want a new issue for the spec (including SIGs) because it's often very challenging to extract the spec change requirements from Q&A conversations. For Learn site changes, sometimes you want a summary but sometimes the Q&A really illustrates what needs documenting, so I think we can be more flexible there.

If we do this, we should copy the "needs author response" / "no recent activity" issue automation over.

Overlaps that need to be de-duped or moved

• move README.md "Participation" section (link to new location)
• move TOB.md
• move GOVERNANCE.md
• update community SPECIAL_INTEREST_GROUPS.md and remove the one here
• maybe move some of DEVELOPMENT.md like "Participation" and "Community Roles"
• do we need CODE_OF_CONDUCT.md in each repo? It is also the only thing in OAI/.github because GitHub looks for certain things there (I have not checked whether they are all in sync)
• we could move the weekly meeting issues and workflow over there, but if that Thursday meeting stays focused primarily on OAS I'd probably keep it here. The community meeting can link to the meeting agendas for various repos/SIGs.

[lornajane]

My first question: who handles the questions we move to a repo that nobody is actively using or looking at? I have no problem at all in having userland questions coming in on the spec repo - and at least that repo has some eyes on it. Moving the content to a location that does not have experienced bystanders hanging around could be a miss IMO.

As a future side-effect, it might help to keep community questions on the various versions separate so we direct questions to the correct versioned repo eventually. Because I still see OpenAPI 2.0 questions, and also I think the biggest winners in OpenAPI 4.0 are not the 3.1 users (it's too early to say that though really!) who are already pretty well served. We should be preparing to support two communities over an extended period. Or perhaps I mean provide space for separate community support to occur.

[handrews]

@lornajane Those are all very good points. Some questions to maybe help work through them:

• Are there that many experienced bystanders who actually currently answer questions who wouldn't get the news of the shift - I feel like most people who reply are on slack and/or go to one of the meetings and would figure it out quickly
• If we have user questions in the community repo, not only is it more clearly outside of the versioning scheme, it could also have a custom issue form that requires users to specify the spec version (and maybe sections) that they're asking about. It would be much easier to manage 2.0 questions in another repo, as they feel very out of place here and are just noise from the spec development perspective
• Would it be better to move the 3.x spec development out of this repo, as we have done with Moonwalk, and just let this be the de-facto community repo?
• If we can't split one or the other out into a new repository, can we make either issues or discussions about customer support, and the other one about spec work? It's possible to transfer issues to discussions and vice-versa

I do feel very strongly about the mix of user support and spec work being a problem - it's my number one frustration with the project on a day-to-day basis. As much as I wish we could approve PRs faster, that's just a normal constraint of volunteer projects - we can't add more hours to the day or pay full-time employees. But we can do something to separate the work and make it manageable. We need to be able to see what we're doing, not just a random mix of conversations. idk, maybe that's just me, but I find the current situation immensely frustrating.

[lornajane]

I think the spec work has to happen here, since it's where we keep the spec. I think (especially with discussions and projects in play) we can manage with people bringing everything to this repo, and that there's merit in making everyone welcome here, and then ruthlessly tagging, classifying, and "gardening" what comes in so that spec contributors (and people working on other specific aspects of the project) can find the signal in the noise.

[handrews]

I think various changes and our more active community have made it so this is not as much of a concern for me. I'm going to close it out and we can revisit the idea if we really need to. We're now down to 250 open issues (counting this one I'm about to close!), 9 open discussions, and we now have an issue-filing menu that directs questions to Slack and open-ended proposals to discussions.