Reviewing for approvers and reviewers
Every week a specific docs approver volunteers to triage and review pull requests. This person is the “PR Wrangler” for the week. See the PR Wrangler scheduler for more information. To become a PR Wrangler, attend the weekly SIG Docs meeting and volunteer. Even if you are not on the schedule for the current week, you can still review pull requests (PRs) that are not already under active review.
In addition to the rotation, a bot assigns reviewers and approvers for the PR based on the owners for the affected files.
- Reviewing a PR
- Commit into another person’s PR
- Prow commands for reviewing
- Triage and categorize issues
- Adding and removing issue labels
- Handling special issue types
Reviewing a PR
Kubernetes documentation follows the Kubernetes code review process.
Everything described in Reviewing a pull request applies, but Reviewers and Approvers should also do the following:
/assignProw command to assign a specific reviewer to a PR as needed. This is extra important when it comes to requesting technical review from code contributors.Note: Look at the
reviewersfield in the front-matter at the top of a Markdown file to see who can provide technical review.
- Making sure the PR follows the Content and Style guides; link the author to the relevant part of the guide(s) if it doesn’t.
- Using the GitHub Request Changes option when applicable to suggest changes to the PR author.
- Changing your review status in GitHub using the
/lgtmProw commands, if your suggestions are implemented.
Commit into another person’s PR
Leaving PR comments is helpful, but there might be times when you need to commit into another person’s PR instead.
Do not “take over” for another person unless they explicitly ask you to, or you want to resurrect a long-abandoned PR. While it may be faster in the short term, it deprives the person of the chance to contribute.
The process you use depends on whether you need to edit a file that is already in the scope of the PR, or a file that the PR has not yet touched.
You can’t commit into someone else’s PR if either of the following things is true:
If the PR author pushed their branch directly to the https://github.com/kubernetes/website/ repository. Only a reviewer with push access can commit to another user’s PR.Note: Encourage the author to push their branch to their fork before opening the PR next time.
- The PR author explicitly disallows edits from approvers.
Prow commands for reviewing
the Kubernetes-based CI/CD system that runs jobs against pull requests (PRs). Prow
enables chatbot-style commands to handle GitHub actions across the Kubernetes
organization, like adding and removing labels, closing issues, and assigning an approver. Enter Prow commands as GitHub comments using the
The most common prow commands reviewers and approvers use are:
|Prow Command||Role Restrictions||Description|
|Anyone, but triggers automation if a Reviewer or Approver uses it||Signals that you’ve finished reviewing a PR and are satisfied with the changes.|
|Approvers||Approves a PR for merging.|
|Reviewers or Approvers||Assigns a person to review or approve a PR|
|Reviewers or Approvers||Closes an issue or PR.|
|Anyone||Adds the |
|Anyone||Removes the |
See the Prow command reference to see the full list of commands you can use in a PR.
Triage and categorize issues
In general, SIG Docs follows the Kubernetes issue triage process and uses the same labels.
This GitHub Issue filter finds issues that might need triage.
Triaging an issue
- Validate the issue
- Make sure the issue is about website documentation. Some issues can be closed quickly by answering a question or pointing the reporter to a resource. See the Support requests or code bug reports section for details.
- Assess whether the issue has merit.
- Add the
triage/needs-informationlabel if the issue doesn’t have enough detail to be actionable or the template is not filled out adequately.
- Close the issue if it has both the
- Add a priority label (the Issue Triage Guidelines define priority labels in detail)
|Do this right now.|
|Do this within 3 months.|
|Do this within 6 months.|
|Deferrable indefinitely. Do when resources are available.|
|Placeholder for a potentially good issue so it doesn’t get lost.|
|Suitable for someone with very little Kubernetes or SIG Docs experience. See Help Wanted and Good First Issue Labels for more information.|
At your discretion, take ownership of an issue and submit a PR for it (especially if it’s quick or relates to work you’re already doing).
If you have questions about triaging an issue, ask in
#sig-docs on Slack or
the kubernetes-sig-docs mailing list.
Adding and removing issue labels
To add a label, leave a comment in one of the following formats:
/<label-category> <label-to-add>(for example,
To remove a label, leave a comment in one of the following formats:
/remove-<label-category> <label-to-remove>(for example,
In both cases, the label must already exist. If you try to add a label that does not exist, the command is silently ignored.
For a list of all labels, see the website repository’s Labels section. Not all labels are used by SIG Docs.
Issue lifecycle labels
Issues are generally opened and closed quickly. However, sometimes an issue is inactive after its opened. Other times, an issue may need to remain open for longer than 90 days.
|After 90 days with no activity, an issue is automatically labeled as stale. The issue will be automatically closed if the lifecycle is not manually reverted using the |
|An issue with this label will not become stale after 90 days of inactivity. A user manually adds this label to issues that need to remain open for much longer than 90 days, such as those with a |
Handling special issue types
SIG Docs encounters the following types of issues often enough to document how to handle them.
If a single problem has one or more issues open for it, combine them into a single issue.
You should decide which issue to keep open (or
open a new issue), then move over all relevant information and link related issues.
Finally, label all other issues that describe the same problem with
triage/duplicate and close them. Only having a single issue to work on reduces confusion
and avoids duplicate work on the same problem.
Dead link issues
If the dead link issue is in the API or
kubectl documentation, assign them
/priority critical-urgent until the problem is fully understood. Assign all other dead link issues
/priority important-longterm, as they must be manually fixed.
We expect Kubernetes Blog entries to become outdated over time. Therefore, we only maintain blog entries less than a year old. If an issue is related to a blog entry that is more than one year old, close the issue without fixing.
Support requests or code bug reports
Some docs issues are actually issues with the underlying code, or requests for
assistance when something, for example a tutorial, doesn’t work.
For issues unrelated to docs, close the issue with the
triage/support label and a comment
directing the requester to support venues (Slack, Stack Overflow) and, if
relevant, the repository to file an issue for bugs with features (
is a great place to start).
Sample response to a request for support:
This issue sounds more like a request for support and less like an issue specifically for docs. I encourage you to bring your question to the `#kubernetes-users` channel in [Kubernetes slack](http://slack.k8s.io/). You can also search resources like [Stack Overflow](http://stackoverflow.com/questions/tagged/kubernetes) for answers to similar questions. You can also open issues for Kubernetes functionality in https://github.com/kubernetes/kubernetes. If this is a documentation issue, please re-open this issue.
Sample code bug report response:
This sounds more like an issue with the code than an issue with the documentation. Please open an issue at https://github.com/kubernetes/kubernetes/issues. If this is a documentation issue, please re-open this issue.
Was this page helpful?
Thanks for the feedback. If you have a specific, answerable question about how to use Kubernetes, ask it on Stack Overflow. Open an issue in the GitHub repo if you want to report a problem or suggest an improvement.