Incentivize maintainership: Formalize which teams are maintainers

[jack-berg]

Parent issue: Incentivize maintainership for long-term project health

Proposal

Establish a formal definition of which GitHub teams represent maintainers, codified in workstreams.yml.

Today, there are 73 GitHub teams with names ending in -maintainers, but there is no authoritative mapping between these teams and the SIGs defined in workstreams.yml. Some teams were created for projects that never materialized, some are redundant due to parent-child relationships, and other various quirks.

If we're going to tie governance rights to maintainer status — voting weight, project proposal roles, roadmap participation — we need a clear, auditable answer to "who is a maintainer?"

Why workstreams.yml

workstreams.yml is already the source of truth for how the project organizes its work. Each SIG entry includes its people (GC liaison, TC sponsors), meetings, Slack channels, and repositories. It's the natural place to also declare which GitHub team represents maintainers for each SIG.

This would extend each SIG entry with something like:

- id: java-sdk-instrumentation
  kind: sig
  ...
  people:
  - gcLiaison: trask
  - tcSponsor:
      username: jack-berg
      level: leading
  - maintainerTeam: java-maintainers   # <-- new
  resources:
  - repository: open-telemetry/opentelemetry-java
  ...

What this enables

• Clear governance scope. When a process says "maintainers vote on X," we know exactly which teams and people that includes.
• Auditable membership. workstreams.yml is version-controlled and reviewed via PR, unlike ad hoc GitHub team creation.
• Repository ownership. Formalizing the relationship between SIGs, their maintainer teams, and their repositories in one place.
• Cleanup opportunity. Forces us to reconcile the 73 existing -maintainers teams against the actual SIG structure and identify teams that are stale, redundant, or misclassified.

[svrnm]

I think the challenge here might be that there are "repo maintainers" and "SIG maintainers", e.g. for most SIGs there are core and contrib maintainers, which might not be identical. Some SIGs, especially comms might make this even harder, as we have now approvers&maintainers for localizations, the ecosystem explorer, and docs, which are not necessarily the "SIG maintainers", another example is PHP core and PHP distro

[danielgblanco]

@svrnm what are the different roles for localization maintainers & approvers? We were having the same discussion recently in the end-user SIG about blueprints, and how we see approvers at the blueprints level, but not necessarily maintainers (which would be more general across all aspects of the SIG.

[jack-berg]

I think we might need some sort of litmus test with questions like:

• Does this group actively lead SIG meetings? I.e. share screen, keep notes, keep topics.
• Does this group hold merge rights to repo(s)?
• Does this group have admin like responsibilities for repo(s)? I.e. decides repo settings, manages releases, handles advisories.

If the answer is "yes" to 2 or more of these questions, the group is a maintainer group.

Something like that.

---

as we have now approvers&maintainers for localizations, the ecosystem explorer, and docs, which are not necessarily the "SIG maintainers",

I was looking at that. My initial reaction was that having maintainers for each of the localizations seemed like a bit of a stretch, but when I looked at the composition of those teams they were mostly the docs-maintainers with a few extra people. What does the litmus test above tell us about these teams?

another example is PHP core and PHP distro

PHP distro is its own repo which publishes its own artifact which has a bunch of maintenance tasks and scope outside of opentelemetry-php, so I think that's a distinct set of maintainers. At least it would meet the definition of the litmus test above.

[svrnm]

If the answer is "yes" to 2 or more of these questions, the group is a maintainer group.

I like that test, it's a good indication for what a maintainer is, although the "lead SIG meetings" is not true for all of them, see below.

as we have now approvers&maintainers for localizations, the ecosystem explorer, and docs, which are not necessarily the "SIG maintainers",

I was looking at that. My initial reaction was that having maintainers for each of the localizations seemed like a bit of a stretch, but when I looked at the composition of those teams they were mostly the docs-maintainers with a few extra people. What does the litmus test above tell us about these teams?

The thing is, that we still have not formalized what a localization maintainer actually is, as they currently work of the opentelemetrydotio repo and we are reluctant to move to a multi-repo setup, although the single repo setup is a permission nightmare, but that's not a problem for here. Let's ignore localization as a corner case for now.

another example is PHP core and PHP distro

PHP distro is its own repo which publishes its own artifact which has a bunch of maintenance tasks and scope outside of opentelemetry-php, so I think that's a distinct set of maintainers. At least it would meet the definition of the litmus test above.

I don't think there is a dedicated SIG meeting for them, as there are no dedicated SIG meetings for most -contrib repos I guess?

[jack-berg]

I don't think there is a dedicated SIG meeting for them, as there are no dedicated SIG meetings for most -contrib repos I guess?

Java instrumentation doesn't have a separate SIG meeting. The java SIG is shared between core java and instrumentation. Yet there's zero doubt that java instrumentation maintainers, which are separate from java core maintainers, are maintainers. Litmus test works here as well.