Define criteria for filing/closing issues vs discussions

[handrews]

We know we have a backlog problem. Right now, the focus is on closing very old and stale issues, particularly ones that are out of date or never got any sort of traction.

We also often close things that are out of scope, or are clearly not going to be addressed because of some design principle of OpenAPI. It would be good to define and document as many of these as we can so we can reference the criteria, and close more things with confidence.

Ideally, if we are going to continue with both issues and discussions, this should include criteria for migrating from one to the other. Loosely speaking, issues are good for things that can be clearly mapped to actions, while discussions are good for exploring options when the topic is complex, or when it's not obvious which of several possible actions we might want to take, if any.

Issue #3508 regarding transferring issues/discussions to Moonwalk is somewhat related.

Some things I think are good reasons to close (just the first few that came to mind):

• JSON Schema concerns, including new proposed extensions, are out of scope for OpenAPI 3.1+
• Proposals that limit what sort of HTTP APIs can be described go against the "big tent" principle
• Proposals that are too oriented towards either strictly or loosely typed languages, at the expense of the other category, also go against the "big tent" principle

These would join other obvious categories like "Questions about tools do not belong in the spec repo."

[miqui]

Sounds, good @handrews. @darrelmiller , @lornajane , @earth2marsh - kinda feel powerless, since I can't even label any issues. Would be nice to be able to label issues that could be (should be) closed.

[handrews]

@miqui once the new TSC members are in place, they'll look at expanding @OAI/triage which is the group that can do those things (and close issues, actually - just can't merge PRs).

[handrews]

I've proposed moving community Q&A to OAI/community (#3561), which would make this process question a lot simpler. We could keep actionable items as issues and open-ended discussions as discussions. Currently we're using two tools (issues and discussions) semi-interchangeably for three purposes.

If we move community questions out, closure criteria for issues becomes obvious (it's either resolved or we declare that we won't do it). Closure for discussions is more difficult, but since discussions sort by recent activity, an open backlog is less of a problem there.

[handrews]

Specific questions to consider:

• What JSON Schema-related requests, if any, remain in-scope for the project? And can we close all the rest as out-of-scope?
• Resolve other OAI scope questions and document the decisions

[handrews]

Copying @lornajane 's comment from https://github.com/OAI/OpenAPI-Specification/issues/3614#issuecomment-1984137500:

We should start new ideas off as discussions on this repository, once general agreement is reached, those ideas can become a proposal in a pull request. The proposal has a formalised format, which means we can then use it to make changes to the specification, so it's a good outcome. The idea is to have something that just needs polishing once it's in proposal format.

Should we now move issues that feel more open-ended to discussions? Should we move more focused discussions to issues? And what are we doing with all the community support stuff?

[lornajane]

I think we need to put out guidance before we start moving things, in case that makes someone feel they are "doing it wrong" because we rewrote the unwritten processes.

I've opened #3673 to try to formalise the proposal part of the process which should help to get ideas going to a new place. If usage questions should be discussions on the community repo (or issues, or somewhere else), we need to make that very clear both here and wherever they are going instead, and direct answerers as well as questioners to mingle in that space.