open-telemetry / opentelemetry-specification

Specifications for OpenTelemetry
https://opentelemetry.io
Apache License 2.0
3.75k stars 889 forks source link

Rework spec issue management #3821

Open jack-berg opened 10 months ago

jack-berg commented 10 months ago

As of the writing of this (1/10/24), this repository has 646 open issues. The process of submitting an issue, triaging, and making a contribution to resolve leaves a lot to be desired for both authors of issues and TC members who are responsible for maintaining the spec.

I've done some analysis on the process we use today and want to propose a series of changes to rework it.

Problems

Proposal

Screenshot 2024-01-12 at 3 23 28 PM

Outcomes

I hope that by adopting this proposal, we can:

yurishkuro commented 10 months ago

One other aspect that I think is missing is the expiration / timeout of issues. If we have no expiration, then issues with deciding:community-feedback might sit around forever, creating the same backlog that we're trying to avoid. Ditto for accepted:needs-sponsor. I would suggest:

If there are more "waiting" states they should all have predefined timeout periods and a downgrade path.

jack-berg commented 10 months ago

I agree with that. The counter I've heard in the past is that closing issues just hides issues. But having an intractable number of open issues doesn't provide any additional visibility over closing them. I would advocate for adopting a culture where we close issues which are stale and are comfortable re-opening them when they are relevant again.

carlosalberto commented 10 months ago

Overall good, only a minor non-blocking comment:

PRs submitted to address the issue prior to a sponsor volunteering should be rejected.

I've seen this a lot for small corrections and clarifications, and probably we should me more lenient at first? Holding them from merging or blocking while issue & triaging take shape, etc.

danielgblanco commented 9 months ago

I think it's a great approach and very clear workflow. Minor question, I assume a single approver can mark an issue as triage:rejected:declined and close it, as they understand it doesn't align with the project goals/strategy. If this decision is appealed by the author and re-opened, do we expect a different approver to pick it up, or at least get involved? Trying to avoid personal back and forth between two individuals.

joaopgrassi commented 9 months ago

I really liked the proposal, and whatever we come up here, will probably make sense to also use in the semconv repo. I feel a lot of people that contribute to the spec are also contributing to semconv so it would be nice that the user experience across repos is the same.

joaopgrassi commented 9 months ago

The collector also has some nice process: https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/CONTRIBUTING.md#triage-process

austinlparker commented 3 weeks ago

We've been doing the new spec issue management process for a few months now; How's it going? Are we good to call this complete?