Participating in SIG-DOCS
SIG-DOCS is one of the special interest groups within the Kubernetes project, focused on writing, updating, and maintaining the documentation for Kubernetes as a whole.
SIG Docs welcomes content and reviews from all contributors. Anyone can open a pull request (PR), and anyone is welcome to comment on content or pull requests in progress.
Within the Kubernetes project, you may also become a member, reviewer, or approver. These roles confer additional privileges and responsibilities when it comes to approving and committing changes. See community-membership for more information on how membership works within the Kubernetes community.
Roles and Responsibilities
The automation reads /hold, /lgtm, and /approve comments and sets labels on the pull request.
When a pull request has the lgtm and approve labels without any hold labels, the pull request merges automatically.
Kubernetes org members, and reviewers and approvers for SIG Docs can add comments to control the merge automation.
- Members
Any member of the Kubernetes organization can review a pull request, and SIG Docs team members frequently request reviews from members of other SIGs for technical accuracy.
SIG Docs also welcomes reviews and feedback regardless of Kubernetes org membership.
You can indicate your approval by adding a comment of /lgtm to a pull request.
- Reviewers
Reviewers are individuals who review documentation pull requests.
Automation assigns reviewers to pull requests, and contributors can request a review with a comment on the pull request: /assign [@_github_handle].
To indicate that a pull request requires no further changes, a reviewer should add comment to the pull request /lgtm.
A reviewer indicates technical accuracy with a lgtm comment.
Reviewers can add a /hold comment to prevent the pull request from being merged.
Another reviewer or approver can remove a hold with the comment: /hold cancel.
When a reviewer is assigned a pull request to review it is not a sole responsibility, and any other reviewer may also offer their opinions on the pull request. If a reviewer is requested, it is generally expected that the PR will be left to that reviewer to do their editorial pass on the content. If a PR author or SIG Docs maintainer requests a review, refrain from merging or closing the PR until the requested reviewer completes their review.
- Approvers
Approvers have the ability to merge a PR.
Approvers can indicate their approval with a comment to the pull request: /approve.
An approver is indicating editorial approval with the an /approve comment.
Approvers can add a /hold comment to prevent the pull request from being merged.
Another reviewer or approver can remove a hold with the comment: /hold cancel.
Approvers may skip further reviews for small pull requests if the proposed changes appear trivial and/or well-understood.
An approver can indicate /lgtm or /approve in a PR comment to have a pull request merged, and all pull requests require at least one approver to provide their vote in order for the PR to be merged.
Note: There is a special case when an approver uses the comment: /lgtm. In these cases, the automation will add both lgtm and approve tags, skipping any further review.
+{: .note }
For PRs that require no review (typos or otherwise trivial changes), approvers can enter an lgtm comment, indicating no need for further review and flagging the PR with approval to merge.
Teams and groups within SIG Docs
You can get an overview of SIG Docs from the community github repo. The SIG Docs group defines two teams on Github:
These groups maintain the Kubernetes website repository, which houses the content hosted at this site.
Both can be referenced with their @name in github comments to communicate with everyone in that group.
These teams overlap, but do not exactly match, the groups used by the automation tooling. For assignment of issues, pull requests, and to support PR approvals, the automation uses information from the OWNERS file.
To volunteer as a reviewer or approver, make a pull request and add your Github handle to the relevant section in the OWNERS file.
Note: Reviewers and approvers must meet requirements for participation. For more information, see the Kubernetes community repository.
Documentation for the OWNERS explains how to maintain OWNERS for each repository that enables it.
The Kubernetes website repository has two automation (prow) plugins enabled:
- blunderbuss
- approve
These two plugins use the OWNERS and OWNERS_ALIAS files in our repo for configuration.
What’s next
For more information about contributing to the Kubernetes documentation, see:
- Review the SIG Docs Style Guide.
- Learn how to stage your documentation changes.
- Learn about writing a new topic.
- Learn about using page templates.
- Learn about staging your changes.
- Learn about creating a pull request.
- How to generate documentation: