Update the maintainers/editors for v1?

[earth2marsh]

The maintainers list lists an older TSC member list. It might be updated, removed, or pointed to the OpenAPI Specification's document (reduce future toil).

There is a separate editors list that might also deserve a review before v1 launch?

[ralfhandl]

@earth2marsh The EDITORS.md file is used by the respec script to populate the "Editors:" list in the HTML version of the spec.

• Preview: https://ralfhandl.github.io/OpenAPI-Specification/overlay/v1.0.0.html

Please comment here or open a PR if it needs to be changed.

[earth2marsh]

I'm suddenly wobbly about what "editors" means!

Contributors suggests people who submit PRs that then get merged. It could also include people who join discussions/issues/Slack/Zoom discussions.

Maintainers maps onto the TSC in terms of people who review/approve merges for OAS. (CODEOWNERS also intersects a bit?)

So what then does Editors mean? It seems like it serves like it credits the people behind the document (not unlike RFC authors). Is that accurate? If so, what are the criteria for inclusion?

[ralfhandl]

My take, aligned with my top ten Google results:

• Contributors contribute content, they cannot publish it.
• Editors publish content and try their best to assure its consistency and correctness. They may also be contributors.

Translated to our current setup:

• Contributor is anyone who creates a PR that is merged.
• Editors are maintainers that merge PRs.

For OAS this is reflected in the three different files CONTRIBUTORS.md, EDITORS.md, and MAINTAINERS.md, although the CONTRIBUTORS.md currently requires 25 merged PRs - we could (should?) relax that.

For Overlay the CONTRIBUTORS.md is missing, and the MAINTAINERS.md is outdated.

[handrews]

@ralfhandl is the CONTRIBUTORS.md file actually used for anything or does it just sit there separate from the spec publishing process?

[dret]

@ralfhandl, what do you expect me to do here?

[ralfhandl]

what do you expect me to do here?

Nothing, wrong button 🙄

[ralfhandl]

does it just sit there separate from the spec publishing process

Exactly 😎

[lornajane]

I'd like to propose removing the contributors file. Pull requests are not the only valued activity on our projects, and it doesn't send the correct message IMO.

[handrews]

@lornajane agreed, I've filed OAI/OpenAPI-Specification#4148 to track.

[lornajane]

I think we did update the editors list, but I note that we still have an outdated list of maintainers. Should we update this to list the current TSC members for the main project, or does Overlays have its own maintainers?

[ralfhandl]

Not sure why we would need this file.

If we decide to need it, I'd empty it except for a link to the OAS file.