From baeef8c126e04bfe4ccc0b0eda71bbc4744a0ede Mon Sep 17 00:00:00 2001 From: Aimee Ukasick Date: Wed, 9 Oct 2019 11:15:57 -0500 Subject: [PATCH] Add best practices to Review docs pull requests Simply and reduce language in bullet points Signed-off-by: Aimee Ukasick --- content/en/docs/contribute/start.md | 70 ++++++++++++++++++----------- 1 file changed, 43 insertions(+), 27 deletions(-) diff --git a/content/en/docs/contribute/start.md b/content/en/docs/contribute/start.md index 43f2e02b73206..12c8202f1ff67 100644 --- a/content/en/docs/contribute/start.md +++ b/content/en/docs/contribute/start.md @@ -46,10 +46,10 @@ weekly video meetings. New participants are welcome. For more information, see ### Content guildelines -The SIG Docs community created guidelines about what kind of content is allowed -in the Kubernetes documentation. Look over the [Documentation 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 +The SIG Docs community created guidelines about what kind of content is allowed +in the Kubernetes documentation. Look over the [Documentation 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 content in the [#sig-docs](#participate-in-sig-docs-discussions) Slack 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 empty square brackets (`[ ]`), put an `x` between the set of brackets that represents the appropriate choice. If you have a proposed solution to fix - the issue, add it. + the issue, add it. - **Request a new page** @@ -126,7 +126,7 @@ in mind: - 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 with a large scope, break them down into smaller issues. - + For instance, "Fix the security docs" is not an actionable issue, but "Add details to the 'Restricting network access' topic" might be. - 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 description later. {{< /note >}} - + Click **Propose file change**. The change is saved as a commit in a new branch in your fork, which is automatically named something like `patch-1`. @@ -244,24 +244,24 @@ description later. 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 **Create pull request**. - + {{< note >}} 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 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. {{< /note >}} - + 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 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, - 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, - 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 **Create pull request**. - + Congratulations! Your pull request is available in [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. {{< 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 >}} 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** 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 - 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 - once every 7 days. You can also drop into #sig-docs Slack channel, + 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 + 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. 7. If your change is accepted, a reviewer merges your pull request, and the @@ -294,15 +294,31 @@ contribution guide. ## Review docs pull requests -People who are not yet approvers or reviewers can still review pull requests. -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. Take a look at the -[Content](/docs/contribute/style/content-guide/) and -[Style](/docs/contribute/style/style-guide/) guides before you review so you +People who are new to documentation can still review pull requests. You can +learn the code base and build trust with your fellow contributors. English docs +are the authoritative source for content. We communicate in English during +weekly meetings and in community announcements. Contributors' English skills +vary, so use simple and direct language in your reviews. Effective reviews focus +on both small details and a change's potential impact. + +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. +### 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 [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 @@ -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 appears. - 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 - leave multiple comments and notifies the PR owner only when you have - completed the review, rather than a separate notification for each comment. + 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 + leave multiple comments and notifies the PR owner only when you have + 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 summarize your review, and you can choose to comment, approve, or request