Governance & Workflow
Relevant source files
The following files were used as context for generating this wiki page:
The Grafana project operates under a defined governance model and technical workflow designed to ensure project stability, community health, and consistent release cycles. These processes emphasize "rough consensus" and lightweight procedures while maintaining strict requirements for code quality and security.
Governance rules apply to the entire Grafana ecosystem, including core repositories and associated plugins like grafana-plugin-sdk-go and worldmap-panel. The technical workflow follows trunk-based development, ensuring that the main branch is always in a deployable state.
Sources: GOVERNANCE.md:5-20, WORKFLOW.md:5-15, CONTRIBUTING.md:1-10
Project Roles and Governance structure
The project is managed by a tiered structure of contributors with varying levels of responsibility and authority.
Team Roles
- Team Members: Individuals who have made ongoing contributions for at least three months. Membership is granted via a formal proposal and supermajority vote.
- Maintainers: Leaders of individual projects or subsystems. They serve as the point of conflict resolution and have final approval authority on significant changes.
- Contributors: Any individual participating in the community by reporting bugs, suggesting features, or submitting code.
Sources: GOVERNANCE.md:10-25, GOVERNANCE.md:105-125
Decision Making and Voting
Grafana primarily operates on Rough Consensus, meaning decisions are supported as long as no major objections are raised. If consensus cannot be reached, formal voting is used.
| Vote Type | Quorum/Requirement | Application |
|---|---|---|
| Consensus | Implicit agreement if silent | Technical issues, daily operations |
| Majority Vote | > 50% of those voting | Resolving technical stalemates |
| Supermajority | ≥ 2/3 of eligible voters | New team members, member removal |
Sources: GOVERNANCE.md:165-220
The following diagram illustrates the decision-making transition from consensus to formal voting:
The decision-making flow ensures that the project only resorts to formal voting when community consensus fails.
Sources: GOVERNANCE.md:165-210
Code Contribution Workflow
All code changes MUST target the main branch and be submitted via Pull Requests (PRs). Direct merges to main are strictly prohibited.
Proposing Changes
Depending on the complexity, changes should be proposed through different channels:
- Direct PR: Small, trivial changes.
- Issue: Standard bug fixes or feature enhancements.
- Developer Mailing List: Complex architectural changes.
- Design Document: Significant overarching changes (shared via Google Docs).
Sources: WORKFLOW.md:25-35, contribute/create-pull-request.md:10-25
Pull Request (PR) Requirements
To be accepted, a PR must meet several criteria:
- Reviewers: Must be approved by at least one team member. Non-trivial changes require two team members or one maintainer. Significant changes require two team members AND the relevant subsystem maintainer.
- Formatting: Titles must follow the
<Area>: <Summary>format (e.g.,Docs: Update contributing guide). - Testing: Must include tests that verify the intended behavior or replicate a fixed bug.
- Sign-off: Contributors must sign the Contributor License Agreement (CLA).
Sources: WORKFLOW.md:40-55, contribute/create-pull-request.md:30-45, CONTRIBUTING.md:140-145
PR Merging Process
The workflow for merging a PR involves automated checks and manual reviews:
The PR lifecycle ensures code quality through automated linting/testing and multi-person review.
Sources: contribute/merge-pull-request.md:10-40, contribute/create-pull-request.md:100-115
Issue Triage and Prioritization
Incoming issues are categorized and prioritized to manage the project backlog effectively. Many triage actions are automated via GitHub Actions.
Categorization Labels
- type/bug: Feature not working as intended.
- type/feature-request: Proposals for new functionality.
- priority/critical: Data loss, security issues, or unusable features.
- triage/needs-confirmation: Issues that cannot be immediately reproduced.
Sources: contribute/ISSUE_TRIAGE.md:150-180, contribute/ISSUE_TRIAGE.md:250-265
Prioritization Matrix
| Label | Description |
|---|---|
priority/critical | Top priority; active work required immediately. |
priority/important-soon | Staffed for the next release. |
priority/nice-to-have | Good idea, but unscheduled. |
priority/awaiting-more-evidence | Lowest priority; lacks community interest. |
Sources: contribute/ISSUE_TRIAGE.md:235-255
Release Workflow
Grafana follows a trunk-based development model with a predictable release cadence.
Release Cadence
- MAJOR: Yearly.
- MINOR: Every 4–6 weeks.
- PATCH: As needed for critical bug fixes.
Sources: WORKFLOW.md:105-110
Branching Structure
- Main Branch: Always stable and passing builds.
- Release Branches: Split from
mainfor Major/Minor releases. Patch releases are split from the current patch of the Minor branch. - Feature Flags: Used for larger changes to allow frequent merges into
mainwithout exposing incomplete features to users.
Sources: WORKFLOW.md:80-100
Backporting Policy
Backporting is the process of copying a PR into previous version branches. This is reserved for:
- Critical bug fixes: Must be coordinated with the delivery team.
- Documentation changes: Specifically
type/docs. - Security fixes: Prepared in secret and not including unrelated changes.
Sources: WORKFLOW.md:60-65, contribute/merge-pull-request.md:135-150, WORKFLOW.md:100-105
Summary
The Governance and Workflow of Grafana provide a balanced environment where consensus-driven development is supported by strict technical standards. By utilizing automated triage and trunk-based releases, the project maintains a high velocity while ensuring that the core product remains stable for its global user base.
Sources: GOVERNANCE.md:230-240, WORKFLOW.md:115-120