Skip to content

Commit 5c9773b

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #22001 from celestehorgan/add-prefernences
Make roles and responsibilities its own page
2 parents a325ddb + 7e3940f commit 5c9773b

File tree

3 files changed

+310
-316
lines changed

3 files changed

+310
-316
lines changed

‎content/en/docs/contribute/participate/_index.md

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
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/participating/roles-and-responsibilities/#members),
24+
[reviewer](/docs/contribute/participating/roles-and-responsibilities/#reviewers), or [approver](/docs/contribute/participating/roles-and-responsibilities/#approvers). These roles require greater
25+
access and entail certain responsibilities for approving and committing changes.
26+
See [community-membership](https://github.com/kubernetes/community/blob/master/community-membership.md)
27+
for more information on how membership works within the Kubernetes community.
28+
29+
The rest of this document outlines some unique ways these roles function within
30+
SIG Docs, which is responsible for maintaining one of the most public-facing
31+
aspects of Kubernetes -- the Kubernetes website and documentation.
32+
33+
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 assignment of issues, pull requests, and to support PR approvals,
62+
the automation uses information from `OWNERS` files.
63+
64+
### OWNERS files and front-matter
65+
66+
The Kubernetes project uses an automation tool called prow for automation
67+
related to GitHub issues and pull requests. The
68+
[Kubernetes website repository](https://github.com/kubernetes/website) uses
69+
two [prow plugins](https://github.com/kubernetes/test-infra/tree/master/prow/plugins):
70+
71+
- blunderbuss
72+
- approve
73+
74+
These two plugins use the
75+
[OWNERS](https://github.com/kubernetes/website/blob/master/OWNERS) and
76+
[OWNERS_ALIASES](https://github.com/kubernetes/website/blob/master/OWNERS_ALIASES)
77+
files in the top level of the `kubernetes/website` GitHub repository to control
78+
how prow works within the repository.
79+
80+
An OWNERS file contains a list of people who are SIG Docs reviewers and
81+
approvers. OWNERS files can also exist in subdirectories, and can override who
82+
can act as a reviewer or approver of files in that subdirectory and its
83+
descendants. For more information about OWNERS files in general, see
84+
[OWNERS](https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md).
85+
86+
In addition, an individual Markdown file can list reviewers and approvers in its
87+
front-matter, either by listing individual GitHub usernames or GitHub groups.
88+
89+
The combination of OWNERS files and front-matter in Markdown files determines
90+
the advice PR owners get from automated systems about who to ask for technical
91+
and editorial review of their PR.
92+
93+
## How merging works
94+
95+
When a pull request is merged to the branch used to publish content, that content is published to http://kubernetes.io. To ensure that
96+
the quality of our published content is high, we limit merging pull requests to
97+
SIG Docs approvers. Here's how it works.
98+
99+
- When a pull request has both the `lgtm` and `approve` labels, has no `hold`
100+
labels, and all tests are passing, the pull request merges automatically.
101+
- Kubernetes organization members and SIG Docs approvers can add comments to
102+
prevent automatic merging of a given pull request (by adding a `/hold` comment
103+
or withholding a `/lgtm` comment).
104+
- Any Kubernetes member can add the `lgtm` label by adding a `/lgtm` comment.
105+
- Only SIG Docs approvers can merge a pull request
106+
by adding an `/approve` comment. Some approvers also perform additional
107+
specific roles, such as [PR Wrangler](/docs/contribute/advanced#be-the-pr-wrangler-for-a-week) or
108+
[SIG Docs chairperson](#sig-docs-chairperson).
109+
110+
111+
112+
## {{% heading "whatsnext" %}}
113+
114+
115+
For more information about contributing to the Kubernetes documentation, see:
116+
117+
- [Contributing new content](/docs/contribute/overview/)
118+
- [Reviewing content](/docs/contribute/review/reviewing-prs)
119+
- [Documentation style guide](/docs/contribute/style/)

‎content/en/docs/contribute/participate/roles-and-responsibilties.md

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
---
2+
title: Roles and responsibilities
3+
content_type: concept
4+
weight: 10
5+
---
6+
7+
<!-- overview -->
8+
9+
Anyone can contribute to Kubernetes. As your contributions to SIG Docs grow, you can apply for different levels of membership in the community.
10+
These roles allow you to take on more responsibility within the community.
11+
Each role requires more time and commitment. The roles are:
12+
13+
- Anyone: regular contributors to the Kubernetes documentation
14+
- Members: can assign and triage issues and provide non-binding review on pull requests
15+
- Reviewers: can lead reviews on documentation pull requests and can vouch for a change's quality
16+
- Approvers: can lead reviews on documentation and merge changes
17+
18+
<!-- body -->
19+
20+
## Anyone
21+
22+
Anyone with a GitHub account can contribute to Kubernetes. SIG Docs welcomes all new contributors!
23+
24+
Anyone can:
25+
26+
- Open an issue in any [Kubernetes](https://github.com/kubernetes/) repository, including [`kubernetes/website`](https://github.com/kubernetes/website)
27+
- Give non-binding feedback on a pull request
28+
- Contribute to a localization
29+
- Suggest improvements on [Slack](http://slack.k8s.io/) or the [SIG docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs).
30+
31+
After [signing the CLA](/docs/contribute/new-content/overview/#sign-the-cla), anyone can also:
32+
33+
- Open a pull request to improve existing content, add new content, or write a blog post or case study
34+
- Create diagrams, graphics assets, and embeddable screencasts and videos
35+
36+
For more information, see [contributing new content](/docs/contribute/new-content/).
37+
38+
## Members
39+
40+
A member is someone who has submitted multiple pull requests to `kubernetes/website`. Members are a part of the [Kubernetes GitHub organization](https://github.com/kubernetes).
41+
42+
Members can:
43+
44+
- Do everything listed under [Anyone](#anyone)
45+
- Use the `/lgtm` comment to add the LGTM (looks good to me) label to a pull request
46+
47+
{{< note >}}
48+
Using `/lgtm` triggers automation. If you want to provide non-binding approval, simply commenting "LGTM" works too!
49+
{{< /note >}}
50+
- Use the `/hold` comment to block merging for a pull request
51+
- Use the `/assign` comment to assign a reviewer to a pull request
52+
- Provide non-binding review on pull requests
53+
- Use automation to triage and categorize issues
54+
- Document new features
55+
56+
### Becoming a member
57+
58+
After submitting at least 5 substantial pull requests and meeting the other [requirements](https://github.com/kubernetes/community/blob/master/community-membership.md#member):
59+
60+
1. Find two [reviewers](#reviewers) or [approvers](#approvers) to [sponsor](/docs/contribute/advanced#sponsor-a-new-contributor) your membership.
61+
62+
Ask for sponsorship in the [#sig-docs channel on Slack](https://kubernetes.slack.com) or on the
63+
[SIG Docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs).
64+
65+
{{< note >}}
66+
Don't send a direct email or Slack direct message to an individual
67+
SIG Docs member. You must request sponsorship before submitting your application.
68+
{{< /note >}}
69+
70+
2. Open a GitHub issue in the [`kubernetes/org`](https://github.com/kubernetes/org/) repository. Use the **Organization Membership Request** issue template.
71+
72+
3. Let your sponsors know about the GitHub issue. You can either:
73+
- Mention their GitHub username in an issue (`@<GitHub-username>`)
74+
- Send them the issue link using Slack or email.
75+
76+
Sponsors will approve your request with a `+1` vote. Once your sponsors approve the request, a Kubernetes GitHub admin adds you as a member. Congratulations!
77+
78+
If your membership request is not accepted you will receive feedback. After addressing the feedback, apply again.
79+
80+
4. Accept the invitation to the Kubernetes GitHub organization in your email account.
81+
82+
{{< note >}}
83+
GitHub sends the invitation to the default email address in your account.
84+
{{< /note >}}
85+
86+
## Reviewers
87+
88+
Reviewers are responsible for reviewing open pull requests. Unlike member feedback, you must address reviewer feedback. Reviewers are members of the [@kubernetes/sig-docs-{language}-reviews](https://github.com/orgs/kubernetes/teams?query=sig-docs) GitHub team.
89+
90+
Reviewers can:
91+
92+
- Do everything listed under [Anyone](#anyone) and [Members](#members)
93+
- Review pull requests and provide binding feedback
94+
95+
{{< note >}}
96+
To provide non-binding feedback, prefix your comments with a phrase like "Optionally: ".
97+
{{< /note >}}
98+
99+
- Edit user-facing strings in code
100+
- Improve code comments
101+
102+
You can be a SIG Docs reviewer, or a reviewer for docs in a specific subject area.
103+
104+
### Assigning reviewers to pull requests
105+
106+
Automation assigns reviewers to all pull requests. You can request a
107+
review from a specific person by commenting: `/assign
108+
[@_github_handle]`.
109+
110+
If the assigned reviewer has not commented on the PR, another reviewer can step in. You can also assign technical reviewers as needed.
111+
112+
### Using `/lgtm`
113+
114+
LGTM stands for "Looks good to me" and indicates that a pull request is technically accurate and ready to merge. All PRs need a `/lgtm` comment from a reviewer and a `/approve` comment from an approver to merge.
115+
116+
A `/lgtm` comment from reviewer is binding and triggers automation that adds the `lgtm` label.
117+
118+
### Becoming a reviewer
119+
120+
When you meet the
121+
[requirements](https://github.com/kubernetes/community/blob/master/community-membership.md#reviewer), you can become a SIG Docs reviewer. Reviewers in other SIGs must apply separately for reviewer status in SIG Docs.
122+
123+
To apply:
124+
125+
1. Open a pull request that adds your GitHub user name to a section of the
126+
[OWNERS_ALIASES](https://github.com/kubernetes/website/blob/master/OWNERS) file
127+
in the `kubernetes/website` repository.
128+
129+
{{ note }}
130+
If you aren't sure where to add yourself, add yourself to `sig-docs-en-reviews`.
131+
{{ /note }}
132+
133+
2. Assign the PR to one or more SIG-Docs approvers (user names listed under `sig-docs-{language}-owners`).
134+
135+
If approved, a SIG Docs lead adds you to the appropriate GitHub team. Once added, [K8s-ci-robot](https://github.com/kubernetes/test-infra/tree/master/prow#bots-home) assigns and suggests you as a reviewer on new pull requests.
136+
137+
## Approvers
138+
139+
Approvers review and approve pull requests for merging. Approvers are members of the
140+
[@kubernetes/sig-docs-{language}-owners](https://github.com/orgs/kubernetes/teams/?query=sig-docs) GitHub teams.
141+
142+
Approvers can do the following:
143+
144+
- Everything listed under [Anyone](#anyone), [Members](#members) and [Reviewers](#reviewers)
145+
- Publish contributor content by approving and merging pull requests using the `/approve` comment
146+
- Propose improvements to the style guide
147+
- Propose improvements to docs tests
148+
- Propose improvements to the Kubernetes website or other tooling
149+
150+
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.
151+
152+
153+
### Approving pull requests
154+
155+
Approvers and SIG Docs leads are the only ones who can merge pull requests into the website repository. This comes with certain responsibilities.
156+
157+
- Approvers can use the `/approve` command, which merges PRs into the repo.
158+
159+
{{< warning >}}
160+
A careless merge can break the site, so be sure that when you merge something, you mean it.
161+
{{< /warning >}}
162+
163+
- Make sure that proposed changes meet the [contribution guidelines](/docs/contribute/style/content-guide/#contributing-content).
164+
165+
If you ever have a question, or you're not sure about something, feel free to call for additional review.
166+
167+
- Verify that Netlify tests pass before you `/approve` a PR.
168+
169+
<img src="/images/docs/contribute/netlify-pass.png" width="75%" alt="Netlify tests must pass before approving" />
170+
171+
- Visit the Netlify page preview for a PR to make sure things look good before approving.
172+
173+
- Participate in the [PR Wrangler rotation schedule](https://github.com/kubernetes/website/wiki/PR-Wranglers) for weekly rotations. SIG Docs expects all approvers to participate in this
174+
rotation. See [Be the PR Wrangler for a week](/docs/contribute/advanced#be-the-pr-wrangler-for-a-week)
175+
for more details.
176+
177+
### Becoming an approver
178+
179+
When you meet the [requirements](https://github.com/kubernetes/community/blob/master/community-membership.md#approver), you can become a SIG Docs approver. Approvers in other SIGs must apply separately for approver status in SIG Docs.
180+
181+
To apply:
182+
183+
1. Open a pull request adding yourself to a section of the [OWNERS_ALIASES](https://github.com/kubernetes/website/blob/master/OWNERS) file in the `kubernetes/website` repository.
184+
185+
{{ note }}
186+
If you aren't sure where to add yourself, add yourself to `sig-docs-en-owners`.
187+
{{ /note }}
188+
189+
2. Assign the PR to one or more current SIG Docs approvers.
190+
191+
If approved, a SIG Docs lead adds you to the appropriate GitHub team. Once added, [K8s-ci-robot](https://github.com/kubernetes/test-infra/tree/master/prow#bots-home) assigns and suggests you as a reviewer on new pull requests.

0 commit comments

Comments
 (0)