proposal: add proposal for issue/PR label convention

proposals/0065-issue-pr-label-system.md

@@ -0,0 +1,276 @@
+# Issue and Pull Request Label System
+
+* **Owners:**
+  * `@jan--f`
+
+* **Implementation Status:** `Not implemented`
+
+* **Related Issues and PRs:**
+  * [PROM-66](https://github.com/prometheus/proposals/pull/66)
+
+* **Other docs or links:**
+  * [Kubernetes Label Documentation](https://github.com/kubernetes/test-infra/blob/master/label_sync/labels.md)
+
+> TL;DR: This proposal establishes a label system for issues and pull requests
+> in Prometheus projects, providing clear signals about what needs attention
+> from reviewers or authors, what is actionable, and what is blocked. The
+> system is inspired by Kubernetes labels and designed to work with automated
+> tooling (see PROM-66).
+
+## Why
+
+As Prometheus projects grow, the volume of issues and pull requests increases.
+
+Without a clear labeling system, it becomes difficult to:
+
+- Identify which issues and PRs need immediate attention
+- Understand whether action is required from maintainers, reviewers or author
+- Clearly mark items that can be worked on by (new) contributors versus ones that need to be evaluated for validity, e.g. bugs that are considered invalid
+- Maintain an efficient review and triage workflow
+
+A systematic approach to labels helps contributors and maintainers quickly
+understand the state of any issue or PR and take appropriate action.
+
+### Pitfalls of the current solution
+
+Currently, there is no standardized label system across Prometheus projects. This leads to:
+
+- Inconsistent labeling practices across repositories
+- Difficulty in identifying what requires attention
+- PRs and issues that languish without clear ownership or next steps
+- No clear signal for when an item is blocked versus ready for action
+- Maintainer time wasted re-evaluating items that haven't changed state
+- Contributors time wasted by working on untriaged issues which might be invalid
+
+## Goals
+
+Goals and use cases for the solution as proposed in [How](#how):
+
+* Provide clear signals about issue and PR lifecycle states
+* Make it obvious which items need attention from reviewers versus authors
+* Distinguish between actionable items and those waiting on external dependencies
+* Enable automated tooling to assist with workflow management
+* Create consistency across Prometheus ecosystem repositories
+* Reduce maintainer cognitive load when evaluating what needs attention
+* Help new contributors to identify suitable issues to work on
+
+### Audience
+
+This proposal targets:
+
+- Prometheus maintainers who need to triage and review issues/PRs
+- Contributors who need to understand the state of their submissions
+- New contributors who are looking for issues to work on
+- Automated tooling that helps manage workflow
+
+## Non-Goals
+
+* Defining how labels are automatically applied (this will be covered in a separate proposal)
+* Creating labels for every possible state or condition
+* Retroactively labeling all existing issues and PRs
+
+## How
+
+### Label Categories
+
+This proposal defines three core label categories (plus an optional fourth for future use) that work together to manage issue and PR workflow:
+
+#### 1. Triage Labels
+
+These labels indicate whether an issue has been evaluated and is ready for work:
+
+- **`triage/needs-triage`**: Initial state for all new issues. Indicates the issue needs initial evaluation by a maintainer to determine validity, priority, and next steps.
+- **`triage/accepted`**: Issue has been triaged and accepted as valid work. It is ready for someone to work on.
+- **`triage/needs-information`**: Issue needs more details from the author before it can be properly evaluated or worked on.
+
+**Workflow**: All issues start with `triage/needs-triage`. During triage,
+maintainers either replace this with another triage label or remove it entirely.
+
+Instead a `kind/` label should be added. The absence of any triage label (along
+with issue comments) indicates that triage action has been taken and the issue
+is currently being worked on. Declined or duplicate issues should also have no
+`triage/` label.
+
+#### 2. Review Labels
+
+These labels manage the pull request review lifecycle:
+
+- **`review/needs-review`**: Initial state for all new PRs. Indicates the PR needs review from maintainers.
+- **`review/changes-requested`**: Reviewers have requested changes. Author action is needed.
+- **`review/lgtm`**: "Looks Good To Me" - PR has received approval from reviewers. If an approving reviewer is code owner the PR is ready to be merged.
+
+**Workflow**: All PRs start with `review/needs-review`. After review, this transitions to either `review/changes-requested` or `review/lgtm`. After requested changes have been addressed, a PR transitions back to `review/needs-review`. Once approved by appropriate maintainers, it becomes `review/lgtm`.
+
+#### 3. Blocking Labels
+
+These labels indicate that an issue or PR cannot proceed:
+
+- **`blocked/needs-decision`**: Waiting for architectural or design decision
+  from maintainers or community.
+- **`blocked/hold`**: Explicitly placed on hold by a maintainer. Should not be merged or closed even if otherwise ready.
+
+**Workflow**: These labels can be applied at any time when the item becomes blocked. They should be removed when the blocking condition is resolved.
+
+#### 4. Lifecycle Labels
+
+These labels track the activity status of issues and PRs. Prometheus has an [automation in place](https://github.com/prometheus/prometheus/blob/96d3d641e329c049f649edbd4c2695345c027c56/.github/workflows/stale.yml) that would only require adjusting the label values.
+
+- **`lifecycle/stale`**: No activity for an extended period (currently 30 days). Candidate for closure if no activity resumes.
+- **`lifecycle/keepalive`**: Should not be marked stale due to inactivity. Reserved for important long-running items.
+
+### Label Interactions
+
+Labels from different categories work together:
+
+- **Active PR ready for review**: `review/needs-review` (no blocking labels)
+- **PR waiting on author**: `review/changes-requested`
+- **PR approved but held**: `review/lgtm` + `blocked/hold`
+- **Issue accepted and ready**: `triage/accepted` (no blocking labels)
+- **Issue needing more info**: `triage/needs-information`
+- **Issue declined or duplicate**: No triage label (removed after triage with explanatory comment)
+
+### Existing Label Taxonomies
+
+This section documents the existing label taxonomies currently in use across
+Prometheus repositories, particularly in prometheus/prometheus. These labels are
+included here for documentation purposes, to reflect current practice and to propose
+how to handle these labels going forward.
+
+#### Component and area Labels
+
+Component labels indicate which part of the codebase an issue or PR affect.
+Area labels provide additional categorization for cross-cutting concerns.
+A few examples of currently used labels:
+
+- **`component/api`**: HTTP API
+- **`component/promql`**: PromQL query engine
+- **`component/promtool`**: promtool CLI utility
+- **`component/rules`**: Recording and alerting rules
+- **`component/scraping`**: Metric scraping and service discovery
+- **`component/service discovery`**: Service discovery mechanisms
+- **`component/tsdb`**: Time series database (storage engine)
+- **`component/ui`**: Web UI
+- **`area/build`**: Build system and build process
+- **`area/ci-cd`**: Continuous integration and deployment
+- **`area/opentelemetry`**: OpenTelemetry integration and compatibility
+- **`area/utf8`**: UTF-8 support and related issues
+
+**Usage**: Issues and PRs typically have one or more component labels to
+indicate the affected areas. Multiple component labels may be applied if changes
+span multiple components. Area labels are less commonly used than component
+labels and typically indicate cross-cutting concerns or specific initiatives.
+
+**Proposal**: Keep the `component/` and `area/` prefixes and leave the suffixes
+unspecified so that developers can add them as needed. Move any current labels
+to use the prefixes where needed.
+
+#### Kind Labels
+
+Kind labels categorize the type of change or issue:
+
+- **`kind/bug`**: Something is broken or not working as intended
+- **`kind/enhancement`**: Improvement to existing functionality
+- **`kind/feature`**: Entirely new functionality
+- **`kind/cleanup`**: Code cleanup, refactoring or technical debt reduction
+- **`kind/optimization`**: Performance improvements
+- **`kind/change`**: General change that doesn't fit other categories
+- **`kind/breaking`**: Breaking change that affects backward compatibility
+
+**Usage**: Issues and PRs typically have exactly one kind label to indicate the primary nature of the change. The kind label helps communicate the impact and urgency of the change.
+
+**Proposal**: Keep the labels and recommend to add them manually to issues after
+triage and to PRs as needed.
+
+#### Priority Labels
+
+Priority labels indicate the urgency and importance of an issue or PR:
+
+- **`priority/P0`**: Critical priority - requires immediate attention (e.g., production outages, security issues)
+- **`priority/P1`**: High priority - should be addressed in the current release cycle
+- **`priority/P2`**: Medium priority - should be addressed soon but not urgent
+- **`priority/P3`**: Low priority - nice to have but can wait
+- **`priority/Pmaybe`**: Lowest priority - may or may not be addressed; needs further discussion
+
+**Usage**: Priority labels are typically assigned during triage and help maintainers and contributors understand what to work on first. Not all issues have priority labels assigned.
+
+**Proposal**: Remove `priority/Pmaybe`. The absence of a `triage/` label and a
+respective comment should clearly state whether an issue can be worked on or
+not. Keep the other labels and recommend to use as needed.
+
+#### Other Common Labels
+
+Many other labels are currently in use. Many overlap with the taxonomy proposed
+here, for example:
+
+- **`duplicate`**: Duplicate of another issue
+- **`invalid`**: Issue is not valid or is spam
+- **`won't fix`**: Issue will not be addressed
+- **`stale`**: No recent activity
+- **`keepalive`**: Should not be marked stale or auto-closed
+
+Some currently used labels are well established and seem useful but don't fit
+well into the proposed taxonomy:
+
+- **`help wanted`**: Good issues for external contributors, might require specific expertise
+- **`good first issue`**: Good for newcomers to the project
+- **`not-as-easy-as-it-looks`**: Appears simple but has hidden complexity
+- `dependencies`: Used by dependeabot
+
+A few labels have served a temporary purpose:
+
+- `hacktoberfest`
+- `backport-*`: Track backports for LTS releases
+
+**Usage**: These labels serve various workflow and community needs. Some are
+applied manually, while others (like `dependencies`) are often applied
+automatically.
+
+**Proposal**: Most labels should be abandoned in favor of the structured labels
+proposed above. Keep a few regular exceptions and the option for temporary
+labels for a specific purpose.
+
+### Implementation Considerations
+
+This proposal focuses on defining the label taxonomy. A separate proposal will address:
+
+- Automation for applying initial labels (e.g., `triage/needs-triage` on new issues)
+- Automation for lifecycle labels based on activity (optional)
+- Integration with tooling to make it easier to apply labels consistently
+
+### Validation
+
+Success will be measured by:
+
+- Reduced time to first triage for new issues
+- Clearer visibility into PR review pipeline
+- Fewer "lost" or forgotten issues and PRs
+- Positive feedback from maintainers about workflow clarity
+- Successful integration with automated tooling
+
+## Alternatives
+
+### Alternative 1: Minimal Label Set
+
+Use only `needs-triage`, `needs-review`, and `hold` labels.
+
+**Rationale for rejection**: Too minimal. Doesn't provide enough granularity to distinguish between "waiting on author" vs "waiting on maintainer" vs "blocked externally", which are common and important states.
+
+### Alternative 2: Use Existing GitHub Features Only
+
+Rely on GitHub's built-in review states, assignees, and milestones without custom labels.
+
+**Rationale for rejection**: GitHub's native features don't provide sufficient granularity for triage states or blocking conditions. Custom labels allow for automation and clearer communication of project-specific workflow.
+
+### Alternative 3: Adopt Kubernetes Labels Exactly
+
+Use the exact label names and taxonomy from Kubernetes.
+
+**Rationale for rejection**: While Kubernetes provides excellent inspiration, Prometheus has different workflow needs. For example, the proposed `review/*` namespace is more explicit than Kubernetes's use of `lgtm` and `approved` at the root level. The proposal aims for clarity over brevity.
+
+## Action Plan
+
+* [ ] Review and accept this proposal (establishes label taxonomy)
+* [ ] Create labels
+* [ ] Pilot the label system in one repository (e.g., prometheus/prometheus)
+* [ ] Document label meanings in contributor guides
+* [ ] Set up automation for lifecycle labels (stale/rotten) (optional)