Learn Kubernetes Basics

Contribute to Kubernetes docs

Kubernetes v1.16 documentation is no longer actively maintained. The version you are currently viewing is a static snapshot. For up-to-date documentation, see the latest version.

Edit This Page

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. See SIG Docs from the community github repo for more information about the SIG.

SIG Docs welcomes content and reviews from all contributors. Anyone can open a pull request (PR), and anyone is welcome to file issues about content or comment on pull requests in progress.

Within SIG Docs, you may also become a member, reviewer, or approver. These roles require greater access and entail certain responsibilities for approving and committing changes. See community-membership for more information on how membership works within the Kubernetes community. The rest of this document outlines some unique ways these roles function within SIG Docs, which is responsible for maintaining one of the most public-facing aspects of Kubernetes – the Kubernetes website and documentation.

Roles and responsibilities

When a pull request is merged to the branch used to publish content (currently master), that content is published and available to the world. To ensure that the quality of our published content is high, we limit merging pull requests to SIG Docs approvers. Here’s how it works.

  • When a pull request has both the lgtm and approve labels and has no hold labels, the pull request merges automatically.
  • Kubernetes organization members and SIG Docs approvers can add comments to prevent automatic merging of a given pull request (by adding a /hold comment or withholding a /lgtm comment).
  • Any Kubernetes member can add the lgtm label, by adding a /lgtm comment.
  • Only an approver who is a member of SIG Docs can cause a pull request to merge by adding an /approve comment. Some approvers also perform additional specific roles, such as PR Wrangler or SIG Docs chairperson.

For more information about expectations and differences between the roles of Kubernetes organization member and SIG Docs approvers, see Types of contributor. The following sections cover more details about these roles and how they work within SIG Docs.

Anyone

Anyone can file an issue against any part of Kubernetes, including documentation.

Anyone who has signed the CLA can submit a pull request. If you cannot sign the CLA, the Kubernetes project cannot accept your contribution.

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 a person’s membership status in the Kubernetes organization. You can indicate your approval by adding a comment of /lgtm to a pull request. If you are not a member of the Kubernetes organization, your /lgtm has no effect on automated systems.

Any member of the Kubernetes organization can add a /hold comment to prevent the pull request from being merged. Any member can also remove a /hold comment to cause a PR to be merged if it already has both /lgtm and /approve applied by appropriate people.

Becoming a member

After you have successfully submitted at least 5 substantive pull requests, you can request membership in the Kubernetes organization. Follow these steps:

  1. Find two reviewers or approvers to sponsor your membership.

    Ask for sponsorship in the #sig-docs channel on the Kubernetes Slack instance or on the SIG Docs mailing list.

    Note: Don’t send a direct email or Slack direct message to an individual SIG Docs member.

  2. Open a GitHub issue in the kubernetes/org repository to request membership. Fill out the template using the guidelines at Community membership.

  3. Let your sponsors know about the GitHub issue, either by at-mentioning them in the GitHub issue (adding a comment with @<GitHub-username>) or by sending them the link directly, so that they can add a +1 vote.

  4. When your membership is approved, the github admin team member assigned to your request updates the GitHub issue to show approval and then closes the GitHub issue. Congratulations, you are now a member!

If for some reason your membership request is not accepted right away, the membership committee provides information or steps to take before applying again.

Reviewers

Reviewers are members of the @kubernetes/sig-docs-pr-reviews GitHub group. See Teams and groups within SIG Docs.

Reviewers review documentation pull requests and provide feedback on proposed changes.

Automation assigns reviewers to pull requests, and contributors can request a review from a specific reviewer with a comment on the pull request: /assign [@_github_handle]. To indicate that a pull request is technically accurate and requires no further changes, a reviewer adds a /lgtm comment to the pull request.

If the assigned reviewer has not yet reviewed the content, another reviewer can step in. In addition, you can assign technical reviewers and wait for them to provide /lgtm.

For a trivial change or one that needs no technical review, the SIG Docs approver can provide the /lgtm as well.

A /approve comment from a reviewer is ignored by automation.

For more about how to become a SIG Docs reviewer and the responsibilities and time commitment involved, see Becoming a reviewer or approver.

Becoming a reviewer

When you meet the requirements, you can become a SIG Docs reviewer. Reviewers in other SIGs must apply separately for reviewer status in SIG Docs.

To apply, open a pull request to add yourself to the reviewers section of the top-level OWNERS file in the kubernetes/website repository. Assign the PR to one or more current SIG Docs approvers.

If your pull request is approved, you are now a SIG Docs reviewer. K8s-ci-robot will assign and suggest you as a reviewer on new pull requests.

If you are approved, request that a current SIG Docs approver add you to the @kubernetes/sig-docs-pr-reviews GitHub group. Only members of the kubernetes-website-admins GitHub group can add new members to a GitHub group.

Approvers

Approvers are members of the @kubernetes/sig-docs-maintainers GitHub group. See Teams and groups within SIG Docs.

Approvers have the ability to merge a PR, and thus, to publish content on the Kubernetes website. To approve a PR, an approver leaves an /approve comment on the PR. If someone who is not an approver leaves the approval comment, automation ignores it.

If the PR already has a /lgtm, or if the approver also comments with /lgtm, the PR merges automatically. A SIG Docs approver should only leave a /lgtm on a change that doesn’t need additional technical review.

For more about how to become a SIG Docs approver and the responsibilities and time commitment involved, see Becoming a reviewer or approver.

Becoming an approver

When you meet the requirements, you can become a SIG Docs approver. Approvers in other SIGs must apply separately for approver status in SIG Docs.

To apply, open a pull request to add yourself to the approvers section of the top-level OWNERS file in the kubernetes/website repository. Assign the PR to one or more current SIG Docs approvers.

If your pull request is approved, you are now a SIG Docs approver. K8s-ci-robot will assign and suggest you as a reviewer on new pull requests.

If you are approved, request that a current SIG Docs approver add you to the @kubernetes/sig-docs-maintainers GitHub group. Only members of the kubernetes-website-admins GitHub group can add new members to a GitHub group.

Approver responsibilities

Approvers improve the documentation by reviewing and merging pull requests into the website repository. Because this role carries additional privileges, approvers have additional responsibilities:

  • Approvers can use the /approve command, which merges PRs into the repo.

    A careless merge can break the site, so be sure that when you merge something, you mean it.

  • Make sure that proposed changes meet the contribution guidelines.

    If you ever have a question, or you’re not sure about something, feel free to call for additional review.

  • Verify that netlify tests pass before you /approve a PR.

    Netlify tests must pass before approving

  • Visit the netlify page preview for a PR to make sure things look good before approving.

PR Wrangler

SIG Docs approvers participate in the PR Wrangler rotation scheduler for weekly rotations. SIG Docs expects all approvers to participate in this rotation. See Be the PR Wrangler for a week for more details.

SIG Docs chairperson

Each SIG, including SIG Docs, selects one or more SIG members to act as chairpersons. These are points of contact between SIG Docs and other parts of the Kubernetes organization. They require extensive knowledge of the structure of the Kubernetes project as a whole and how SIG Docs works within it. See Leadership for the current list of chairpersons.

SIG Docs teams and automation

Automation in SIG Docs relies on two different mechanisms for automation: GitHub groups and OWNERS files.

GitHub groups

The SIG Docs group defines two teams on GitHub:

Each 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 OWNERS files.

OWNERS files and front-matter

The Kubernetes project uses an automation tool called prow for automation related to GitHub issues and pull requests. The Kubernetes website repository uses two prow plugins:

  • blunderbuss
  • approve

These two plugins use the OWNERS and OWNERS_ALIASES files in the top level of the kubernetes/website GitHub repository to control how prow works within the repository.

An OWNERS file contains a list of people who are SIG Docs reviewers and approvers. OWNERS files can also exist in subdirectories, and can override who can act as a reviewer or approver of files in that subdirectory and its descendents. For more information about OWNERS files in general, see OWNERS.

In addition, an individual Markdown file can list reviewers and approvers in its front-matter, either by listing individual GitHub usernames or GitHub groups.

The combination of OWNERS files and front-matter in Markdown files determines the advice PR owners get from automated systems about who to ask for technical and editorial review of their PR.

What's next

For more information about contributing to the Kubernetes documentation, see:

Feedback