Define process for the "proposals" directory

[handrews]

Currently there is an open PR (#3369) adding a new proposal to the /proposals directory. There is also an issue (#3372) which at first glance is just the proposal pasted into an issue after the PR stalled. And there is also a discussion (#3371) with minimal information linking back to the PR (but not the issue).

Setting aside the contents and merit of that specific proposal, what is supposed to happen here? Should this currently be a discussion, an issue, or a PR? The question of what should be an issue or discussion is also part of #3518, but the proposals directory makes it look like you can just file a PR to make a proposal. Is that what we want, or do we only want PRs for proposals that gain a certain amount of traction?

As it is, I think both the person making this proposal and those of us who have tried to figure out what to do with the PR are too confused to do anything with it.

[lornajane]

I like the idea of a proposal as a pull request, because it needs an owner/champion to drive it forward, rather than just make suggestions and then ask us why we haven't done it yet. There's a bit about the process in https://github.com/OAI/OpenAPI-Specification/blob/main/DEVELOPMENT.md but I thought there was a template and that sort of thing for the proposal document and I can't immediately find that.

[handrews]

See also:

• Use designated labels in proposals to link to related issues & pull requests #1905

[lornajane]

Looking more into how the proposal process actually works, it looks like the webhooks proposal might be the only feature to have made the whole journey (and the proposal status is still "Draft", oops!) so I dug through the history of that change to get some idea of how this could work.

• Add support for webhooks as a top-level element #2103 is the pull request that introduced the actual changes to the spec.
• Proposal: Support Webhooks as well as Callbacks #1974 is the pull request that added the proposal to the spec, looks like that was discussed, updated, and then merged before the feature was actually added to the specification itself.

I note that there were minimal changes between what was in the proposal and what we actually opened as a pull request to the spec - so the proposal was a ready-to-use idea, that was merged and then the specification modifications were made at that point.

In the meeting today we discussed the proposal for experimental fields to be added: #2386. In my opinion, the proposal is in good enough shape to be accepted as a proposal in the proposals directory and discussed further. What isn't clear is whether the discussion happens at this stage where the proposal pull request is open (which actually does make sense even though that's not what I said we should do earlier!), or if the proposal should be merged, and then iterated on before it gets a green light for implementation. And since nobody knows, we can decide all over again how this should work and one of us will write it down!

[handrews]

@lornajane Thanks for looking into this - that all makes sense.

I'm generally of the opinion that PRs should be reserved for things where we already have agreement, so that the only discussion in a PR is "does this correctly implement the agreement?"

My rationale is that a long PR list makes it look like a project is not very active. Our PR list as of late last year gave that impression – correctly! So PRs that end up in long debates add way more conceptual clutter than an issue or discussion held open for the same amount of time.

I'd prefer to see a low bar for accepting a proposal into the repo with an initial PR, and follow-up PRs as we discuss and make changes. It's also possible that we could replace the proposals directory with discussions if we:

• make discussions only about open-ended proposals and large topics
• make issues only about relatively actionable things
• make PRs only about doing things that are already agreed-to
• move community Q&A to other places

This is essentially what we're doing in OAI/sig-moonwalk (except there isn't any community Q&A), and it's much easier to see what is happening.

I don't think GitHub discussions existed when we started the proposals process, so we needed a better place to put bigger discussions. It might be that we don't really need that now.

[handrews]

Copying @lornajane 's comment from #3614 (comment):

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.

[lornajane]

I feel like we're converging on a process, but given that we have some cleanup to do on our process documentation, where can I put a document about proposals? Maybe I can add it to the DEVELOPMENT doc for now but shout if that seems like a terrible solution to anyone.

[lornajane]

I think #1862 is also relevant