whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add best practices to Review docs pull requests (#16770)

Browse Source 
Simply and reduce language in bullet points

Signed-off-by: Aimee Ukasick <aimeeu.opensource@gmail.com>
This commit is contained in:
aimeeu
2019-10-14 18:13:50 -05:00
committed by Kubernetes Prow Robot
parent 03456f1a72
commit cf390493af
1 changed files with 43 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/docs/contribute/start.md
+43 -27
View File
@@ -46,10 +46,10 @@ weekly video meetings. New participants are welcome. For more information, see
### Content guidelines ### Content guidelines
The SIG Docs community created guidelines about what kind of content is allowed The SIG Docs community created guidelines about what kind of content is allowed
in the Kubernetes documentation. Look over the [Documentation Content in the Kubernetes documentation. Look over the [Documentation Content
Guide](/docs/contribute/style/content-guide/) to determine if the content Guide](/docs/contribute/style/content-guide/) to determine if the content
contribution you want to make is allowed. You can ask questions about allowed contribution you want to make is allowed. You can ask questions about allowed
content in the [#sig-docs](#participate-in-sig-docs-discussions) Slack content in the [#sig-docs](#participate-in-sig-docs-discussions) Slack
channel. channel.
@@ -106,7 +106,7 @@ you can instead [fix it](#improve-existing-content) without filing a bug first.
Using Markdown, fill in as many details as you can. In places where you see Using Markdown, fill in as many details as you can. In places where you see
empty square brackets (`[ ]`), put an `x` between the set of brackets that empty square brackets (`[ ]`), put an `x` between the set of brackets that
represents the appropriate choice. If you have a proposed solution to fix represents the appropriate choice. If you have a proposed solution to fix
the issue, add it. the issue, add it.
- **Request a new page** - **Request a new page**
@@ -126,7 +126,7 @@ in mind:
- Clearly explain the specific impact the issue has on users. - Clearly explain the specific impact the issue has on users.
- Limit the scope of a given issue to a reasonable unit of work. For problems - Limit the scope of a given issue to a reasonable unit of work. For problems
with a large scope, break them down into smaller issues. with a large scope, break them down into smaller issues.
For instance, "Fix the security docs" is not an actionable issue, but "Add For instance, "Fix the security docs" is not an actionable issue, but "Add
details to the 'Restricting network access' topic" might be. details to the 'Restricting network access' topic" might be.
- If the issue relates to another issue or pull request, you can refer to it - If the issue relates to another issue or pull request, you can refer to it
@@ -232,7 +232,7 @@ Do not include references to other GitHub issues or pull
requests in your commit message. You can add those to the pull request requests in your commit message. You can add those to the pull request
description later. description later.
{{< /note >}} {{< /note >}}
Click **Propose file change**. The change is saved as a commit in a Click **Propose file change**. The change is saved as a commit in a
new branch in your fork, which is automatically named something like new branch in your fork, which is automatically named something like
`patch-1`. `patch-1`.
@@ -244,24 +244,24 @@ description later.
selection boxes, but don't do that now. Have a look at the difference selection boxes, but don't do that now. Have a look at the difference
viewer on the bottom of the screen, and if everything looks right, click viewer on the bottom of the screen, and if everything looks right, click
**Create pull request**. **Create pull request**.
{{< note >}} {{< note >}}
If you don't want to create the pull request now, you can do it If you don't want to create the pull request now, you can do it
later, by browsing to the main URL of the Kubernetes website repository or later, by browsing to the main URL of the Kubernetes website repository or
your fork's repository. The GitHub website will prompt you to create the your fork's repository. The GitHub website will prompt you to create the
pull request if it detects that you pushed a new branch to your fork. pull request if it detects that you pushed a new branch to your fork.
{{< /note >}} {{< /note >}}
5. The **Open a pull request** screen appears. The subject of the pull request 5. The **Open a pull request** screen appears. The subject of the pull request
is the same as the commit summary, but you can change it if needed. The is the same as the commit summary, but you can change it if needed. The
body is populated by your extended commit message (if present) and some body is populated by your extended commit message (if present) and some
template text. Read the template text and fill out the details it asks for, template text. Read the template text and fill out the details it asks for,
then delete the extra template text. If you add to the description `fixes #<000000>` then delete the extra template text. If you add to the description `fixes #<000000>`
or `closes #<000000>`, where `#<000000>` is the number of an associated issue, or `closes #<000000>`, where `#<000000>` is the number of an associated issue,
GitHub will automatically close the issue when the PR merges. GitHub will automatically close the issue when the PR merges.
Leave the **Allow edits from maintainers** checkbox selected. Click Leave the **Allow edits from maintainers** checkbox selected. Click
**Create pull request**. **Create pull request**.
Congratulations! Your pull request is available in Congratulations! Your pull request is available in
[Pull requests](https://github.com/kubernetes/website/pulls). [Pull requests](https://github.com/kubernetes/website/pulls).
@@ -271,16 +271,16 @@ pull request if it detects that you pushed a new branch to your fork.
the same browser window by default. the same browser window by default.
{{< note >}} {{< note >}}
Please limit pull requests to one language per PR. For example, if you need to make an identical change to the same code sample in multiple languages, open a separate PR for each language. Please limit pull requests to one language per PR. For example, if you need to make an identical change to the same code sample in multiple languages, open a separate PR for each language.
{{< /note >}} {{< /note >}}
6. Wait for review. Generally, reviewers are suggested by the `k8s-ci-robot`. 6. Wait for review. Generally, reviewers are suggested by the `k8s-ci-robot`.
If a reviewer asks you to make changes, you can go to the **Files changed** If a reviewer asks you to make changes, you can go to the **Files changed**
tab and click the pencil icon on any files that have been changed by the tab and click the pencil icon on any files that have been changed by the
pull request. When you save the changed file, a new commit is created in pull request. When you save the changed file, a new commit is created in
the branch being monitored by the pull request. If you are waiting on a the branch being monitored by the pull request. If you are waiting on a
reviewer to review the changes, proactively reach out to the reviewer reviewer to review the changes, proactively reach out to the reviewer
once every 7 days. You can also drop into #sig-docs Slack channel, once every 7 days. You can also drop into #sig-docs Slack channel,
which is a good place to ask for help regarding PR reviews. which is a good place to ask for help regarding PR reviews.
7. If your change is accepted, a reviewer merges your pull request, and the 7. If your change is accepted, a reviewer merges your pull request, and the
@@ -294,15 +294,31 @@ contribution guide.
## Review docs pull requests ## Review docs pull requests
People who are not yet approvers or reviewers can still review pull requests. People who are new to documentation can still review pull requests. You can
The reviews are not considered "binding", which means that your review alone learn the code base and build trust with your fellow contributors. English docs
won't cause a pull request to be merged. However, it can still be helpful. Even are the authoritative source for content. We communicate in English during
if you don't leave any review comments, you can get a sense of pull request weekly meetings and in community announcements. Contributors' English skills
conventions and etiquette and get used to the workflow. Take a look at the vary, so use simple and direct language in your reviews. Effective reviews focus
[Content](/docs/contribute/style/content-guide/) and on both small details and a change's potential impact.
[Style](/docs/contribute/style/style-guide/) guides before you review so you
The reviews are not considered "binding", which means that your review alone
won't cause a pull request to be merged. However, it can still be helpful. Even
if you don't leave any review comments, you can get a sense of pull request
conventions and etiquette and get used to the workflow. Familiarize yourself with the
[content guide](/docs/contribute/style/content-guide/) and
[style guide](/docs/contribute/style/style-guide/) before reviewing so you
get an idea of what the content should contain and how it should look. get an idea of what the content should contain and how it should look.
### Best practices
- Be polite, considerate, and helpful
- Comment on positive aspects of PRs as well
- Be empathetic and mindful of how your review may be received
- Assume good intent and ask clarifying questions
- Experienced contributors, consider pairing with new contributors whose work requires extensive changes
### How to find and review a pull request
1. Go to 1. Go to
[https://github.com/kubernetes/website/pulls](https://github.com/kubernetes/website/pulls). [https://github.com/kubernetes/website/pulls](https://github.com/kubernetes/website/pulls).
You see a list of every open pull request against the Kubernetes website and You see a list of every open pull request against the Kubernetes website and
@@ -322,10 +338,10 @@ get an idea of what the content should contain and how it should look.
or room for improvement, hover over the line and click the `+` symbol that or room for improvement, hover over the line and click the `+` symbol that
appears. appears.
You can type a comment, and either choose **Add single comment** or **Start You can type a comment, and either choose **Add single comment** or **Start
a review**. Typically, starting a review is better because it allows you to a review**. Typically, starting a review is better because it allows you to
leave multiple comments and notifies the PR owner only when you have leave multiple comments and notifies the PR owner only when you have
completed the review, rather than a separate notification for each comment. completed the review, rather than a separate notification for each comment.
4. When finished, click **Review changes** at the top of the page. You can 4. When finished, click **Review changes** at the top of the page. You can
summarize your review, and you can choose to comment, approve, or request summarize your review, and you can choose to comment, approve, or request