Docs: Edit of README and other topics in Contribute (part 1 of doc quality project) (#85832)
* Docs: Technical edit of 4 files in Contributing * Fix admonitions * Fix admonition * Fix from code review * Fix from code review * Update contribute/create-pull-request.md * Update contribute/merge-pull-request.md Co-authored-by: Eve Meelan <81647476+Eve832@users.noreply.github.com> * Minor fix * Update contribute/merge-pull-request.md Co-authored-by: Eve Meelan <81647476+Eve832@users.noreply.github.com> * Update contribute/merge-pull-request.md Co-authored-by: Eve Meelan <81647476+Eve832@users.noreply.github.com> * Update contribute/merge-pull-request.md Co-authored-by: Eve Meelan <81647476+Eve832@users.noreply.github.com> * Update contribute/merge-pull-request.md Co-authored-by: Eve Meelan <81647476+Eve832@users.noreply.github.com> * Update contribute/merge-pull-request.md Co-authored-by: Eve Meelan <81647476+Eve832@users.noreply.github.com> * Fix from code review * Update contribute/triage-issues.md Co-authored-by: Eve Meelan <81647476+Eve832@users.noreply.github.com> * Run prettier --------- Co-authored-by: Eve Meelan <81647476+Eve832@users.noreply.github.com> Co-authored-by: Jack Baldry <jack.baldry@grafana.com>
This commit is contained in:
Joseph Perez
co-authored by
Eve Meelan
Jack Baldry
Eve Meelan
Jack Baldry
parent
fddf77ee35
commit
2c8e869799
@@ -1,23 +1,23 @@
|
||||
# Create a pull request
|
||||
|
||||
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:
|
||||
|
||||
- conf/defaults.ini
|
||||
- conf/sample.ini
|
||||
- docs/sources/administration/configuration.md
|
||||
- `conf/defaults.ini`
|
||||
- `conf/sample.ini`
|
||||
- `docs/sources/administration/configuration.md`
|
||||
|
||||
Reference in New Issue
Block a user