This directory contains guides for contributors to the Grafana project.
We're excited that you're considering making a contribution to the Grafana project! This is the place to find guides for contributors to our open-source project.
These are some good resources to explore for developers:
- [Create a pull request](create-pull-request.md)
- [Contribute to our documentation](../contribute/documentation/README.md)
- [Developer guide](developer-guide.md)
- [Triage issues](triage-issues.md)
- [Merge a pull request](merge-pull-request.md)
- [Making changes to the CI pipeline](drone-pipeline.md)
- [Breaking changes in frontend APIs](./breaking-changes-guide/breaking-changes-guide.md)
The `style-guides` directory contains style guides for the Grafana software project and documentation.
Learn how to create great documentation and apps for Grafana:
- [Developer portal](https://grafana.com/developers/) - Find resources for creating apps and plugins to Grafana.
- [Contribute to our documentation](../contribute/documentation/README.md) - Learn how to write and style Grafana documentation.
Find style guides for the Grafana software project:
- [Backend style guide](backend/style-guide.md) for how to style and format backend functionality and code.
- [Frontend style guide](style-guides/frontend.md) for how to style and format the user-facing functionality and code.
- [Redux framework](style-guides/redux.md) for designing the Grafana redux framework.
- [Themes style guide](style-guides/themes.md) for designing and updating Grafana themes.
- [Backend style guide](backend/style-guide.md) - Learn how to style and format backend functionality and code.
- [Frontend style guide](style-guides/frontend.md) - Learn how to style and format the user-facing functionality and code.
- [Redux framework](style-guides/redux.md) - Design the Grafana Redux framework.
- [Themes style guide](style-guides/themes.md) - Design and update Grafana themes.
We're excited that you're considering making a contribution to the Grafana project! This document guides you through the process of creating a [pull request](https://help.github.com/en/articles/about-pull-requests/).
Every contribution to Grafana's software begins with a [pull request](https://help.github.com/en/articles/about-pull-requests/). This document guides you through the process of creating a PR.
## Before you begin
We know you're excited to create your first pull request. Before we get started, read these resources first:
- Learn how to start [Contributing to Grafana](/CONTRIBUTING.md).
- Get started [contributing to Grafana](/CONTRIBUTING.md).
- Make sure your code follows the relevant [style guides](/contribute/style-guides).
- It's recommended you [set up precommit hooks](/contribute/developer-guide.md) to auto-format when you commit
## Your first pull request
If this is your first time contributing to an open-source project on GitHub, make sure you read about [Creating a pull request](https://help.github.com/en/articles/creating-a-pull-request).
If this is your first time contributing to an open-source project on GitHub, make sure you read GitHub's article on [creating a pull request](https://help.github.com/en/articles/creating-a-pull-request).
To increase the chance of having your pull request accepted, make sure your pull request follows these guidelines:
- Title and description matches the implementation.
- Commits within the pull request follow the [Formatting guidelines](#Formatting-guidelines).
- Commits within the pull request follow the [formatting guidelines](#Formatting-guidelines).
- The pull request closes one related issue.
- The pull request contains necessary tests that verify the intended behavior.
- If your pull request has conflicts, rebase your branch onto the main branch.
@ -27,7 +27,7 @@ If the pull request fixes a bug:
- The pull request description must include `Closes #<issue number>` or `Fixes #<issue number>`.
- To avoid regressions, the pull request should include tests that replicate the fixed bug.
## Frontend-specific guidelines
## Guidelines for frontend development
Pull requests for frontend contributions must:
@ -42,76 +42,76 @@ Pull requests for Redux contributions must:
- Use the `actionCreatorFactory` and `reducerFactory` helpers instead of traditional switch statement reducers in Redux. Refer to [Redux framework](/contribute/style-guides/redux.md) for more details.
- Use `reducerTester` to test reducers. Refer to [Redux framework](/contribute/style-guides/redux.md) for more details.
- Not contain code that mutates state in reducers or thunks.
- Not contain code that accesses the reducers state slice directly. Instead, the code should use state selectors to access state.
- Not contain code that accesses the reducer's state slice directly. Instead, the code should use state selectors to access state.
Pull requests that add or modify unit tests that are written in Jest must adhere to these guidelines:
- Don't add snapshots tests. We are incrementally removing existing snapshot tests, we don't want more.
- If an existing unit test is written in Enzyme, migrate it to RTL (React Testing Library), unless you’re fixing a bug. Bug fixes usually shouldn't include any bigger refactoring, so it’s ok to skip migrating the test to RTL.
- Don't add snapshots tests. We are incrementally removing existing snapshot tests, and so we don't want more.
- If an existing unit test is written in Enzyme, migrate it to React Testing Library (RTL), unless you’re fixing a bug. Bug fixes usually shouldn't include any bigger refactoring, so it’s okay to skip migrating the test to RTL.
Pull requests that create new UI components or modify existing ones must adhere to the following accessibility guidelines:
- Use semantic HTML.
- Use ARIA roles, labels and other accessibility attributes correctly. Accessibility attributes should only be used when semantic HTML doesn't satisfy your use case.
- Use the [Grafana theme palette](/contribute/style-guides/themes.md) for styling. It contains colors with good contrast which aids accessibility.
- Use the [Grafana theme palette](/contribute/style-guides/themes.md) for styling. The palette contains colors with good contrast to aid accessibility.
- Use [RTL](https://testing-library.com/docs/dom-testing-library/api-accessibility/) for writing unit tests. It helps to create accessible components.
### Accessibility-specific guidelines
### Guidelines for accessibility
Pull requests that introduce accessibility(a11y) errors - please refer to the [accessibility guidelines](/contribute/style-guides/accessibility.md).
Before submitting pull requests that introduce accessibility (a11y) errors, refer to the [accessibility guidelines](/contribute/style-guides/accessibility.md).
### Betterer
We make use of a tool called [**Betterer**](https://phenomnomnominal.github.io/betterer/) in order to drive long-running code quality improvements. The intention is for this to be as unintrusive as possible, however there are some things to be aware of:
We make use of a tool called [**Betterer**](https://phenomnomnominal.github.io/betterer/) in order to drive long-running code quality improvements. Our intention is for this requirement to be as unintrusive as possible; however, there are some things to be aware of:
- **Betterer runs as a precommit hook**:
- You may see changes to the `.betterer.results` file automatically added to your commits.
- You may get an error when trying to commit something that decreases the overall code quality. You can either fix these errors or temporarily override the checks (e.g. to commit something that's a work in progress) by using`git commit --no-verify`. All errors will eventually have to be fixed before your code can be merged because...
- You may get an error when trying to commit something that decreases the overall code quality. You can either fix these errors or temporarily override the checks (for example, to commit something that's a work in progress). To do so, use`git commit --no-verify`. All errors will eventually have to be fixed before your code can be merged because...
- **Betterer also runs as part of our CI**:
- You may see the following error message in the CI: `Unexpected changes detected in these tests while running in CI mode`. To resolve, merge with the target branch (usually `main`).
- You may see merge conflicts for the `.betterer.results` file. To resolve, merge with the target branch (usually `main`) then run `yarn betterer:merge` and commit.
- You may see the following error message in the CI: `Unexpected changes detected in these tests while running in CI mode`. To resolve the error, merge with the target branch (usually `main`).
- You may see merge conflicts for the `.betterer.results` file. To resolve, merge with the target branch (usually `main`), and then run `yarn betterer:merge` and commit.
## Backend-specific guidelines
## Guidelines for backend development
Please refer to the [backend style guidelines](/contribute/backend/style-guide.md).
Refer to the [backend style guidelines](/contribute/backend/style-guide.md).
## Code review
Once you've created a pull request, the next step is to have someone review your change. A review is a learning opportunity for both the reviewer and the author of the pull request.
If you think a specific person needs to review your pull request, then you can tag them in the description or in a comment. Tag a user by typing the `@` symbol followed by their GitHub username.
If you think a specific person needs to review your pull request, then you can tag them in the description or in a comment. To tag a user on GitHub, go to Reviewers box on the Conversations page and enter the `@` symbol followed by their GitHub username.
We recommend that you read [How to do a code review](https://google.github.io/eng-practices/review/reviewer/) to learn more about code reviews.
## Formatting guidelines
A well-written pull request minimizes the time to get your change accepted. These guidelines help you write good commit messages and descriptions for your pull requests.
A well-written pull request minimizes the time to get your change accepted. The following guidelines help you to write good commit messages and descriptions for your pull requests.
### Commit message format
Grafana uses the guidelines for commit messages outlined in [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/), with the following additions:
Grafana uses the guidelines for commit messages outlined in the article [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/), with the following additions:
- Subject line must begin with the _area_ of the commit.
- A footer in the form of an optional [keyword and issue reference](https://help.github.com/en/articles/closing-issues-using-keywords).
- Footer in the form of an optional [keyword and issue reference](https://help.github.com/en/articles/closing-issues-using-keywords).
#### Area
The area should use upper camel case, e.g. UpperCamelCase.
The _area_ refers to a specific part of Grafana's codebase. It should be given in the upper camel case format. For example: UpperCamelCase.
Prefer using one of the following areas:
- **Build:** Change the build system, or external dependencies
- **Chore:** Change that don't affect functionality
- **Chore:** Change that doesn't affect functionality
- **Dashboard:** Change the Dashboard feature
- **Docs:** Change documentation
- **Explore:** Change the Explore feature
- **Plugins:** Change the ... plugin
- **Plugins:** Change a plugin
For changes to data sources, the area is the name of the data source. For example, AzureMonitor, Graphite, or Prometheus.
For changes to panels, the area is the name of the panel, suffixed with Panel. For example, GraphPanel, SinglestatPanel, or TablePanel.
**Examples**
**Examples of good commit messages**
- `Build: Support publishing MSI to grafana.com`
- `Explore: Add Live option for supported data sources`
@ -129,12 +129,13 @@ The Grafana team _squashes_ all commits into one when we accept a pull request.
We use the pull request title when we generate change logs for releases. As such, we strive to make the title as informative as possible.
**Example:**
`Docs: Change url to URL in all documentation files`
## Configuration changes
If your PR includes configuration changes, all the following files must be changed correspondingly:
If your pull request includes configuration changes, all the following files must be changed correspondingly:
When a pull request has been reviewed and approved by at least one person and all checks have passed it's time to merge the pull request.
When a pull request has been reviewed and approved by at least one person and all checks have passed, then it's time to merge the pull request.
## Who is expected to merge a pull request?
Maintainers are responsible for merging all pull requests. If a maintainer has opened a pull request the general rule is that the same maintainer merges the pull request. If a non-maintainer has opened a pull request it's suggested that one of the maintainers reviewing the pull request merges the pull request.
Maintainers are responsible for merging all pull requests. If a maintainer has opened a pull request, then the general rule is that the same maintainer merges the pull request. If a non-maintainer has opened a pull request, then it's suggested that one of the maintainers who reviews the pull request should merge the pull request.
## Checklist/summary
## Checklist of considerations
The following checklist/summary should give you a quick overview of what to ask/consider before merging a pull request.
Consider (and ask about) the items on the following checklist before merging a pull request:
- Reviewed and approved?
- All checks passed?
- Proper pull request title?
- Add to changelog/release notes?
- Needs backporting?
- Is it reviewed and approved?
- Have all checks passed?
- Does it have a proper pull request title?
- Does it need to be added to the changelog (release notes)?
- Does it need backporting?
## Before merge
Before actually merging a pull request there's a couple of things to take into consideration.
Before actually merging a pull request, consider the following things:
### Status checks
@ -30,74 +30,73 @@ The pull request title should be formatted according to `<Area>: <Summary>` (Bot
Keep the summary short and understandable for the community as a whole.
All commits in a pull request are squashed when merged and the pull request title will be the default subject line of the squashed commit message. It's also used for [changelog/release notes](#include-in-changelog-and-release-notes).
All commits in a pull request are squashed when merged and the pull request title will be the default subject line of the squashed commit message. It's also used for the [changelog](#include-in-changelog-and-release-notes).
**Example:**
`Docs: Change url to URL in all documentation files`
See [formatting guidelines](create-pull-request.md#formatting-guidelines) for more information.
### Assign a milestone
### Assign a milestone (automated)
Several things in the Grafana release process requires at least pull requests to be in a milestone, for example [generating changelog/release notes](#include-in-changelog-and-release-notes).
The Grafana release process uses a bot to automatically assign pull requests to a milestone to make it easier for release managers to track changes. For example, [generating changelog (release note)](#include-in-changelog-and-release-notes) must be in a milestone.
This makes it easier to track what changes go into a certain release. Without this information, release managers have to go through git commits which is not an efficient process.
That being said, _you don't have to assign a milestone manually_ to a pull request. Instead, when it is merged and closed, a bot will then look for the most appropriate milestone and assign it to the pull request.
That being said, _you don't have to assign a milestone manually_ to a pull request.
Instead, when it is merged & closed then a bot will look for the most appropriate miletone and assign it to the pull request.
The bot-assigned milestone should always reflect the branch into which the pull request is merged. For example:
That milestone should always reflect the branch that the pull request is merged into.
For every major and minor release there is a milestone ending with `.x` (e.g. `10.0.x` for the 10.0.x releases).
Pull requests targeting `main` should use the `.x` milestone of the next minor (or major) version (you can find that version number inside the `package.json` file).
Backport pull requests should use the version of the target branch (e.g. `9.4.x` for the `v9.4.x` branch).
- For every major and minor release, there is a milestone ending with `.x` (for example, `10.0.x` for the 10.0.x releases).
- Pull requests targeting `main` use the `.x` milestone of the next minor (or major) version (you can find that version number inside the `package.json` file).
- Backport pull requests use the version of the target branch (for example, `9.4.x` for the `v9.4.x` branch).
### Include in changelog and release notes?
### What to include in changelog and release notes
At Grafana we generate the [changelog](https://github.com/grafana/grafana/blob/main/CHANGELOG.md) and [release notes](https://grafana.com/docs/grafana/latest/release-notes/) based on merged pull requests. Including changes in the changelog/release notes is very important to provide a somewhat complete picture of what changes a Grafana release actually includes.
At Grafana we generate the [changelog](https://github.com/grafana/grafana/blob/main/CHANGELOG.md) and [release notes](https://grafana.com/docs/grafana/latest/release-notes/) based on merged pull requests. Including changes in the changelog (release notes) is very important to provide a relatively complete picture of what changes a Grafana release actually includes.
There's a GitHub action available in the repository named [Update changelog](https://github.com/grafana/grafana/blob/main/.github/workflows/update-changelog.yml) that can manually be triggered to re-generate the changelog and release notes for any release.
There's a GitHub action available in the repository named [Update changelog](https://github.com/grafana/grafana/blob/main/.github/workflows/update-changelog.yml) that can be triggered manually to re-generate the changelog and release notes for any release.
Exactly what changes should be added to the changelog is hard to answer but here's some general guidance:
- Include any bug fix in general.
- Include any change that you think would be interesting for the community as a whole.
- Skip larger features divided in multiple pull requests since they might go into the release blog post/What's New article.
- Use your best judgement and/or ask other maintainers for advice.
- Including a change in error rather than skipping one that should have been there is better.
- Always keep [Format the pull request title](#format-the-pull-request-title) in mind.
- Skip larger features divided into multiple pull requests since they might go into the release's What's New article.
- Use your best judgement and, if you aren't sure, then ask other maintainers for advice.
- It's better to err on the side of inclusion. Introducing an unnecessary or duplicate change in the changelog is better than leaving out a change.
- Always keep the guidelines in [Format the pull request title](#format-the-pull-request-title) in mind.
An active decision to include change in changelog/release notes needs to be taken for every pull request. There's a pull request check named **Changelog Check** that will enforce this. By adding/removing labels on the pull request or updating the pull request title/description the check will be re-evaluated.
An active decision to include a change in the changelog needs to be taken for every pull request. There's a pull request check named **Changelog Check** that enforces this rule. By adding or removing labels on the pull request or updating the pull request title, description, or both, the check is re-evaluated.
#### Skip changelog
If you don't want to include your change in changelog/release notes you need to add a label named **no-changelog** to the pull request.
If you don't want to include your change in changelog, you need to add a label named **no-changelog** to the pull request.
#### Include in changelog/release notes
#### Include in changelog
To include a pull request in the changelog/release notes you need to add a label named `add to changelog` to the pull request. Then additional validation rules is checked:
To include a pull request in the changelog, add a label named `add to changelog` to the pull request. Then the following additional validation rules are checked:
- Title need to be formatted according to [Format the pull request title](#format-the-pull-request-title)
- Description needs to include a breaking change notice if change is labeled to be a breaking change, see Breaking changes below for more information.
- The title must be formatted according to [Format the pull request title](#format-the-pull-request-title)
- The description must include a breaking change notice if the change is labeled to be a breaking change. Refer to [Breaking changes](#breaking-changes) below for more information.
Not complying with above rules can make the **Changelog Check** fail with validation errors.
The changelog/release notes are divided into sections and here's a description of how you make a pull request show up in a certain section.
The changelog is divided into various sections. Here's how to make a description of a pull request show up in a certain section of the release notes:
**Features and enhancements:**
Labeled with `add to changelog` and any of the other section rules don't apply.
Label the pull request with `add to changelog` and any of the other section rules don't apply.
**Bug fixes:**
Labeled with `add to changelog` and either labeled with `type/bug` or the pull request title contains `fix` or `fixes`.
Label the pull request with `add to changelog` and either label with `type/bug` or the pull request title contains `fix` or `fixes`.
**Plugin development fixes & changes:**
**Plugin development fixes and changes:**
Labeled with `area/grafana/ui` or `area/grafana/runtime`.
Label the pull request with `area/grafana/ui` or `area/grafana/runtime`.
**Deprecations:**
In case the pull request introduces a deprecation you should document this. Label the pull request with `add to changelog` and use the following template at the end of the pull request description describing the deprecation change.
In case the pull request introduces a deprecation you should document this. Label the pull request with `add to changelog` and use the following template at the end of the pull request description to describe the deprecation change.
```md
# Deprecation notice
@ -107,7 +106,7 @@ In case the pull request introduces a deprecation you should document this. Labe
**Breaking changes:**
In case the pull request introduces a breaking change you should document this. Label the pull request with `add to changelog` and `breaking change` and use the following template at the end of the pull request description describing the breaking change.
In case the pull request introduces a breaking change you should document this. Label the pull request with `add to changelog` and `breaking change` and use the following template at the end of the pull request description describing the breaking change:
```md
# Release notice breaking change
@ -118,39 +117,44 @@ In case the pull request introduces a breaking change you should document this.
### Backporting
Backporting is the process of copying the pull request into the version branch of one or multiple previous releases.
This is a rare exception, should only be done for _critical bug fixes_, and involves the intervention of a Grafana Labs employee.
If your pull request fixes a critical bug and needs to be backported, add it to the "Critical Bug Release" form so the team can approve the backport and know that a release needs to be made. Specify the correct `backport vx.x` labels for the releases the fix needs to be backported to. Once approved, the backporting process will continue from there.
Backporting is a rare exception, should only be done for _critical bug fixes_, and involves the intervention of a Grafana Labs employee.
If your pull request fixes a critical bug and needs to be backported, add it to the "Critical Bug Release" form so the team can approve the backport and know that a release needs to be made. Specify the correct `backport vx.x` labels for the releases to which the fix needs to be backported. Once approved, the backporting process continues.
#### Required labels
To ensure that we don't backport pull requests that don't need to be backported, i.e. implement new features, and only backport pull requests that address bugs, have a product approval, or refer to docs changes, backport labels need to be followed by either:
We aim to ensure that we don't backport pull requests unnecessarily. The only scenarios for backporting are typically pull requests that address bugs, have a product approval, or refer to documentation changes.
- `type/bug` label: Pull requests which address bugs,
- `product-approved` label: Urgent fixes which need product approval, in order to get merged,
- `type/docs` label: Docs changes.
- `type/ci` label: Changes to the CI automation.
Backport labels need to be followed by either:
- `type/bug` label: Pull requests which address bugs
- `product-approved` label: Urgent fixes which need product approval, in order to get merged
- `type/docs` label: Docs changes
- `type/ci` label: Changes to the CI automation
> **Note:** You can still backport a pull request after it's been merged.
## Doing the actual merge
Time to actually merge the pull request changes. All commits in a pull request are squashed, hence the GitHub `Squash and merge` button is used to initialize the merge.
The best time to actually merge the pull request varies from case to case. All commits in a pull request are squashed.
You can change the commit message before merging. Please remember that developers might use the commit information for tasks like reviewing changes of files, doing Git blame, and resolving merge conflicts.
This will present you with options allowing you to optionally change the commit message before merging. Please remember that developers might use the commit information when reviewing changes of files, doing git blame and resolving merge conflicts etc., trying to quickly figure out what the actual change was. But there's not really any best practices around this, the following is an attempt to bring some guidance.
While there aren't formal best practices around this process, you can consider the following guidance:
Do:
**Do:**
- Make sure the pull request title is formatted properly before merging, this will automatically give you a good and short summary of the commit/change.
- Leave `Co-authored-by:` lines as is so that co-authors will be accounted for the contribution.
- Make sure the pull request title is formatted properly before merging. Doing so automatically gives you a good and short summary of the commit.
- Leave `Co-authored-by:` lines as is so that co-authors are credited for the contribution.
- Remove any commit information that doesn't bring any context to the change.
Consider:
**Consider:**
- Add any references to issues that the pull request fixes/closes/references to ease giving quick context to things. Doing this allows cross-reference between the commit and referenced issue(s).
- Keep any references to issues that the pull request fixes, closes, or references. Doing this allows cross-reference between the commit and referenced issue or issues.
Finalize the merge by clicking on the `Confirm squash and merge` button.
To finalize the merge, click the **Confirm squash and merge** button.
## After the merge
Make sure to close any referenced/related issues. It's recommended to assign the same milestone on the issues that the pull request fixes/closes, but not required.
Make sure to close any referenced or related issues. We recommend that you assign the same milestone on the issues that the pull request fixes or closes, but this isn't required.
Triage helps ensure that issues resolve quickly by:
Triage helps ensure that GitHub issues resolve quickly by:
- Ensuring the issue's intent and purpose is conveyed precisely. This is necessary because it can be difficult for an issue to explain how an end user experiences a problem and what actions they took.
- Giving a contributor the information they need before they commit to resolving an issue.
@ -11,11 +11,11 @@ This document gives you some ideas on what you can do to help. For more informat
## Improve issues
Improve issues by suggesting improvements to the title and description. If you think an issue has formatting issues, bad language, or grammatical errors, post a comment to let the author and maintainers know.
Improve issues by suggesting improvements to the title and description of the issue. If you think an issue has formatting issues, bad language, or grammatical errors, post a comment to let the author and maintainers know.
## Report resolved issues
If you think an issue has been resolved, or is no longer relevant, suggest us to close it. Add a comment on the issue, where you explain the reason it should be closed. Make sure to include any related issues and pull requests.
If you think an issue has been resolved, or is no longer relevant, suggest that we close it. Add a comment on the issue in which you explain the reason that it should be closed. Make sure to include any related issues and pull requests.
## Investigate issues
@ -29,4 +29,4 @@ Read more about [how we prioritize issues](/ISSUE_TRIAGE.md#4-prioritization-of-
## Report duplicates
If you find two issues that describe the same thing, add a comment in one of the issues, with a reference (`#<issuenumber>`) to the other. Explain why you think the issue is duplicated.
If you find two issues that describe the same thing, add a comment in one of the issues. In the comment, include a reference (`#<issuenumber>`) to the duplicate. Explain why you think the issue is duplicated.
Joseph Perez
12 months ago
committed by