|
| 1 | +--- |
| 2 | +title: Participating in SIG Docs |
| 3 | +content_type: concept |
| 4 | +weight: 60 |
| 5 | +card: |
| 6 | + name: contribute |
| 7 | + weight: 60 |
| 8 | +--- |
| 9 | + |
| 10 | +<!-- overview --> |
| 11 | + |
| 12 | +SIG Docs is one of the |
| 13 | +[special interest groups](https://github.com/kubernetes/community/blob/master/sig-list.md) |
| 14 | +within the Kubernetes project, focused on writing, updating, and maintaining |
| 15 | +the documentation for Kubernetes as a whole. See |
| 16 | +[SIG Docs from the community github repo](https://github.com/kubernetes/community/tree/master/sig-docs) |
| 17 | +for more information about the SIG. |
| 18 | + |
| 19 | +SIG Docs welcomes content and reviews from all contributors. Anyone can open a |
| 20 | +pull request (PR), and anyone is welcome to file issues about content or comment |
| 21 | +on pull requests in progress. |
| 22 | + |
| 23 | +You can also become a [member](/docs/contribute/participate/roles-and-responsibilities/#members), |
| 24 | +[reviewer](/docs/contribute/participate/roles-and-responsibilities/#reviewers), or |
| 25 | +[approver](/docs/contribute/participate/roles-and-responsibilities/#approvers). |
| 26 | +These roles require greater access and entail certain responsibilities for |
| 27 | +approving and committing changes. See |
| 28 | +[community-membership](https://github.com/kubernetes/community/blob/master/community-membership.md) |
| 29 | +for more information on how membership works within the Kubernetes community. |
| 30 | + |
| 31 | +The rest of this document outlines some unique ways these roles function within |
| 32 | +SIG Docs, which is responsible for maintaining one of the most public-facing |
| 33 | +aspects of Kubernetes -- the Kubernetes website and documentation. |
| 34 | + |
| 35 | +<!-- body --> |
| 36 | + |
| 37 | +## SIG Docs chairperson |
| 38 | + |
| 39 | +Each SIG, including SIG Docs, selects one or more SIG members to act as |
| 40 | +chairpersons. These are points of contact between SIG Docs and other parts of |
| 41 | +the Kubernetes organization. They require extensive knowledge of the structure |
| 42 | +of the Kubernetes project as a whole and how SIG Docs works within it. See |
| 43 | +[Leadership](https://github.com/kubernetes/community/tree/master/sig-docs#leadership) |
| 44 | +for the current list of chairpersons. |
| 45 | + |
| 46 | +## SIG Docs teams and automation |
| 47 | + |
| 48 | +Automation in SIG Docs relies on two different mechanisms: |
| 49 | +GitHub teams and OWNERS files. |
| 50 | + |
| 51 | +### GitHub teams |
| 52 | + |
| 53 | +There are two categories of SIG Docs [teams](https://github.com/orgs/kubernetes/teams?query=sig-docs) on GitHub: |
| 54 | + |
| 55 | +- `@sig-docs-{language}-owners` are approvers and leads |
| 56 | +- `@sig-docs-{language}-reviewers` are reviewers |
| 57 | + |
| 58 | +Each can be referenced with their `@name` in GitHub comments to communicate with |
| 59 | +everyone in that group. |
| 60 | + |
| 61 | +Sometimes Prow and GitHub teams overlap without matching exactly. For |
| 62 | +assignment of issues, pull requests, and to support PR approvals, the |
| 63 | +automation uses information from `OWNERS` files. |
| 64 | + |
| 65 | +### OWNERS files and front-matter |
| 66 | + |
| 67 | +The Kubernetes project uses an automation tool called prow for automation |
| 68 | +related to GitHub issues and pull requests. The |
| 69 | +[Kubernetes website repository](https://github.com/kubernetes/website) uses |
| 70 | +two [prow plugins](https://github.com/kubernetes/test-infra/tree/master/prow/plugins): |
| 71 | + |
| 72 | +- blunderbuss |
| 73 | +- approve |
| 74 | + |
| 75 | +These two plugins use the |
| 76 | +[OWNERS](https://github.com/kubernetes/website/blob/master/OWNERS) and |
| 77 | +[OWNERS_ALIASES](https://github.com/kubernetes/website/blob/master/OWNERS_ALIASES) |
| 78 | +files in the top level of the `kubernetes/website` GitHub repository to control |
| 79 | +how prow works within the repository. |
| 80 | + |
| 81 | +An OWNERS file contains a list of people who are SIG Docs reviewers and |
| 82 | +approvers. OWNERS files can also exist in subdirectories, and can override who |
| 83 | +can act as a reviewer or approver of files in that subdirectory and its |
| 84 | +descendants. For more information about OWNERS files in general, see |
| 85 | +[OWNERS](https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md). |
| 86 | + |
| 87 | +In addition, an individual Markdown file can list reviewers and approvers in its |
| 88 | +front-matter, either by listing individual GitHub usernames or GitHub groups. |
| 89 | + |
| 90 | +The combination of OWNERS files and front-matter in Markdown files determines |
| 91 | +the advice PR owners get from automated systems about who to ask for technical |
| 92 | +and editorial review of their PR. |
| 93 | + |
| 94 | +## How merging works |
| 95 | + |
| 96 | +When a pull request is merged to the branch used to publish content, that content is published to http://kubernetes.io. To ensure that |
| 97 | +the quality of our published content is high, we limit merging pull requests to |
| 98 | +SIG Docs approvers. Here's how it works. |
| 99 | + |
| 100 | +- When a pull request has both the `lgtm` and `approve` labels, has no `hold` |
| 101 | + labels, and all tests are passing, the pull request merges automatically. |
| 102 | +- Kubernetes organization members and SIG Docs approvers can add comments to |
| 103 | + prevent automatic merging of a given pull request (by adding a `/hold` comment |
| 104 | + or withholding a `/lgtm` comment). |
| 105 | +- Any Kubernetes member can add the `lgtm` label by adding a `/lgtm` comment. |
| 106 | +- Only SIG Docs approvers can merge a pull request |
| 107 | + by adding an `/approve` comment. Some approvers also perform additional |
| 108 | + specific roles, such as [PR Wrangler](/docs/contribute/participate/pr-wranglers/) or |
| 109 | + [SIG Docs chairperson](#sig-docs-chairperson). |
| 110 | + |
| 111 | + |
| 112 | + |
| 113 | +## {{% heading "whatsnext" %}} |
| 114 | + |
| 115 | + |
| 116 | +For more information about contributing to the Kubernetes documentation, see: |
| 117 | + |
| 118 | +- [Contributing new content](/docs/contribute/new-content/overview/) |
| 119 | +- [Reviewing content](/docs/contribute/review/reviewing-prs) |
| 120 | +- [Documentation style guide](/docs/contribute/style/) |
0 commit comments