Permalink
Browse files

Address more feedback

  • Loading branch information...
mistyhacks committed Jul 23, 2018
1 parent c681ac5 commit f595b80109cf47baf45e135dee84302742524e12
@@ -18,36 +18,52 @@ Looking for the [style guide](/docs/contribute/style/style-guide/)?
{{% capture body %}}
## Types of contributor
- A _member_ of the Kubernetes organization has [signed the CLA](/contribute/start#sign-the-cla)
and contributed some time and effort to the project. See
[Community membership](https://github.com/kubernetes/community/blob/master/community-membership.md)
for specific criteria for membership.
- A SIG Docs _reviewer_ is a member of the Kubernetes organization who has
expressed interest in reviewing documentation pull requests and who has been
added to the appropriate Github group and `OWNERS` files in the Github
repository, by a SIG Docs Approver.
- A SIG Docs _approver_ is a member in good standing who has shown a continued
commitment to the project and is granted the ability to merge pull requests
and thus to publish content on behalf of the Kubernetes organization.
Approvers can also represent SIG Docs in the larger Kubernetes community.
Some of the duties of a SIG Docs approver, such as coordinating a release,
require a significant time commitment.
## Ways to contribute
This is not an exhaustive list of ways you can contribute to the Kubernetes
documentation, but it should get your juices flowing.
This list is divided into things anyone can do, things Kubernetes organization
members can do, and things that require a higher level of access and familiarity
with SIG Docs processes. Contributing consistently over time can help you
understand some of the tooling and organizational decisions that have already
been made.
This list is divided into things anyone can do, things Kubernetes project
members can do, and things Kubernetes maintainers can do. The intent is not to
throttle contributions or limit who can do what. Some of the more advanced tasks
require a good understanding of Kubernetes itself, and some of them require a
good understanding of how the Kubernetes documentation toolchain works. In
addition, sticking around for a while helps you understand some of the tooling
and organizational decisions that have already been made.
This is not an exhaustive list of ways you can contribute to the Kubernetes
documentation, but it should help you get started.
- [Anyone](start/)
- [Anyone](/docs/contribute/start/)
- File actionable bugs
- [Member](/docs/contribute/start/)
- Improve existing docs
- Bring up ideas for improvement on Slack or SIG docs mailing list
- Improve docs accessibility
- Provide non-binding feedback on PRs
- Write a blog post or case study
- [Member](intermediate/)
- [Reviewer](/docs/contribute/intermediate/)
- Document new features
- Triage and categorize issues
- Review PRs
- Create diagrams, graphics assets, embeddable screencasts / videos
- Create diagrams, graphics assets, and embeddable screencasts / videos
- Localization
- Contribute to other repos as a docs representative
- Edit user-facing strings in code
- Improve code comments, Godoc
- [Maintainer](advanced/)
- [Approver](/docs/contribute/advanced/)
- Publish contributor content by approving and merging PRs
- Participate in a Kubernetes release team as a docs representative
- Propose improvements to the style guide
@@ -64,7 +64,7 @@ The SIG Docs representative for a given release coordinates the following tasks:
artifacts are published.
Coordinating a release is typically a 3-4 month commitment, and the duty is
rotated among SIG Docs maintainers.
rotated among SIG Docs approvers.
{{% /capture %}}
@@ -10,8 +10,12 @@ weight: 20
This page assumes that you've read and mastered the tasks in the
[start contributing](/docs/contribute/start/) topic and are ready to
learn about more ways to contribute. You need to use the Git command line client
and other tools for some of these tasks.
learn about more ways to contribute.
{{< note >}}
**Note:** Some tasks require you to use the Git command line client and other
tools.
{{< /note >}}
{{% /capture %}}
@@ -25,18 +29,20 @@ to gain, deeper knowledge of the following topic areas:
- Kubernetes concepts
- Kubernetes documentation workflows
- Where and how to find information about upcoming Kubernetes features
- Great research skills in general
- Strong research skills in general
These tasks are not as sequential as the beginner tasks, and there is no
expectation that any one person do all of them all of the time.
These tasks are not as sequential as the beginner tasks. There is no expectation
that one person does all of them all of the time.
## Review pull requests
In any given week, a specific docs maintainer volunteers to do initial triage
and review of [pull requests and issues](#triage-and-categorize-issues). To get
on this list, 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 any given week, a specific docs approver volunteers to do initial triage
and review of [pull requests and issues](#triage-and-categorize-issues). This
person is the "PR Wrangler" for the week. The schedule is maintained using the
[PR Wrangler scheduler(https://github.com/kubernetes/website/wiki/PR-Wranglers).
To be added to this list, 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, an automated system comments on each new PR and
suggests reviewers and approvers for the PR, based on the list of approvers and
@@ -88,15 +94,19 @@ the number of lines the PR changes.
The Kubernetes website repo operates differently than some of the Kubernetes
code repositories when it comes to the roles of reviewers and approvers.
- A reviewer does a technical review, to be sure that the docs are technically
accurate. A reviewer completes that task by leaving a `/lgtm` comment on the
PR. Don't add an `/lgtm` unless you are confident in the technical accuracy
of the documentation modified or introduced in the PR.
- A reviewer reviews pull request content for technical accuracy. A reviewer
indicates that a PR is technically accurate by leaving a `/lgtm` comment on
the PR.
{{< note >}}Don't add an `/lgtm` unless you are confident in the technical
accuracy of the documentation modified or introduced in the PR.{{< /note >}}
- A maintainer does a review from a documentation point of view. Approval can
only be given by people in the `sig-docs-maintainers` list. To approve a PR,
you must be in the `sig-docs-maintainers` group, then leave an `/approved`
comment on the PR.
- An approver reviews pull request content for docs quality and adherence to
SIG Docs guidelines, such as the
[style guide](/docs/contribute/style/style-guide). Only people listed as
approvers in the
[`OWNERS`](https://github.com/kubernetes/website/blob/master/OWNERS) file can
approve a PR. To approve a PR, leave an `/approved` comment on the PR.
A PR is merged when it has both a `/lgtm` comment from anyone in the Kubernetes
organization and an `/approved` comment from an approver in the
@@ -194,7 +204,7 @@ true:
repository, only a reviewer with push access can commit into their PR.
Authors should be encouraged to push their branch to their fork before
opening the PR.
- If the PR author explicitly disallowed edits from maintainers, you can't
- If the PR author explicitly disallowed edits from approvers, you can't
commit into their PR unless they change this setting.
#### If the file is already changed by the PR
@@ -497,7 +507,7 @@ changes look like, you can use the `hugo` command to stage the changes locally.
## Triage and categorize issues
In any given week, a specific docs maintainer volunteers to do initial
In any given week, a specific docs approver volunteers to do initial
[triage and review of pull requests](#review-pull-requests) and issues. To get
on this list, attend the weekly SIG Docs meeting and volunteer. Even if you are
not on the schedule for the current week, you can still review PRs.
@@ -533,7 +543,7 @@ These guidelines are not set in stone and are subject to change.
in the issue, slash commands used in the comments of the issue, or
information in the issue text.
- Some labels are manually added by the person triaging the issue (or the person
reporting the issue, if they are a SIG Docs maintainer).
reporting the issue, if they are a SIG Docs approvers).
- `Actionable`: there seems to be enough information for the issue to be fixed
or acted upon.
- `good first issue`: Someone with limited Kubernetes or SIG Docs experience
@@ -547,7 +557,7 @@ These guidelines are not set in stone and are subject to change.
conform to those outlined in the
[Kubernetes contributor guide](https://github.com/kubernetes/community/blob/master/contributors/guide/issue-triage.md#define-priority), and can be one of `P1`, `P2`, or `P3`, if set.
- To add a label, you can use Github's **Labels** widget if you are a Sig Docs
maintainer. Anyone who is a member of the Kubernetes organization can add a
approver. Anyone who is a member of the Kubernetes organization can add a
label by leaving a comment like `/label <label-to-add>`. The label must
already exist. If you try to add a label that does not exist, the command is
silently ignored.
@@ -19,15 +19,24 @@ See [community-membership](https://github.com/kubernetes/community/blob/master/c
## 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.
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
and has no `hold` labels, the pull request merges automatically. Kubernetes
organization members and SIG Docs approvers can add comments to control
automatic merging of a given pull request.
For more information about expectations and differences between the roles of
Kubernetes organization member and SIG Docs approvers, see
[Types of contributor](/docs/contribute#types-of-contributor).
### Members
Any member of the [Kubernetes organization](https://github.com/kubernetes) 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.
Any member of the [Kubernetes organization](https://github.com/kubernetes) 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.
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
@@ -44,16 +53,16 @@ A reviewer indicates technical accuracy with a `/lgtm` comment.
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.
If a PR author or SIG Docs approver requests a review, refrain from merging or closing the PR until the requested reviewer completes their review.
### Maintainers
### Approvers
Maintainers have the ability to merge a PR.
Approvers have the ability to merge a PR.
Maintainers can indicate their approval with a comment to the pull request: `/approve`.
A maintainer is indicating editorial approval with the an `/approve` comment.
Approvers can indicate their approval with a comment to the pull request: `/approve`.
An approver is indicating editorial approval with the an `/approve` comment.
Maintainers may skip further reviews for small pull requests if the proposed changes appear trivial and/or well-understood.
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 >}}**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.
@@ -271,7 +271,7 @@ contribution guide.
## Review docs pull requests
People who are not yet maintainers or reviewers can still review pull requests.
People who are not yet approvers or reviewers can still review pull requests.
The reviews are not considered "binding", which means that your review alone
won't cause a pull request to be merged. However, it can still be helpful. Even
if you don't leave any review comments, you can get a sense of pull request
@@ -283,7 +283,7 @@ conventions and etiquette and get used to the workflow.
docs.
2. By default, the only filter that is applied is `open`, so you don't see
pull reuests that have already been closed or merged. It's a good idea to
pull requests that have already been closed or merged. It's a good idea to
apply the `cncf-cla: yes` filter, and for your first review, it's a good
idea to add `size/S` or `size/XS`. The `size` label is applied automatically
based on how many lines of code the PR modifies. You can apply filters using
@@ -351,6 +351,6 @@ to submit your proposal.
When you are comfortable with all of the tasks discussed in this topic and you
want to engage with the Kubernetes docs team in deeper ways, read the
[internediate docs contribution guide](/docs/contribute/intermediate/).
[intermediate docs contribution guide](/docs/contribute/intermediate/).
{{% /capture %}}
@@ -14,5 +14,5 @@ tags:
<!--more-->
While code review is focused on code quality and correctness, approval is focused on the holistic acceptance of a contribution. Holistic acceptance includes backwards/forwards compatibility, adhering to API and flag conventions, subtle performance and correctness issues, interactions with other parts of the system, and others. Approver status is scoped to a part of the codebase.
While code review is focused on code quality and correctness, approval is focused on the holistic acceptance of a contribution. Holistic acceptance includes backwards/forwards compatibility, adhering to API and flag conventions, subtle performance and correctness issues, interactions with other parts of the system, and others. Approver status is scoped to a part of the codebase. Approvers were previously referred to as maintainers.

This file was deleted.

Oops, something went wrong.
@@ -230,6 +230,9 @@
/docs/reference/generated/kubefed_options/ /docs/reference/setup-tools/kubefed/kubefed-options/ 301
/docs/reference/generated/kubefed_unjoin/ /docs/reference/setup-tools/kubefed/kubefed-unjoin/ 301
/docs/reference/generated/kubefed_version/ /docs/reference/setup-tools/kubefed/kubefed-version/ 301
/docs/reference/glossary/maintainer/ /docs/reference/glossary/approver/ 301
/docs/reference/kubectl/kubectl/kubectl_*.md /docs/reference/generated/kubectl/kubectl-commands#:splat 301
/docs/reference/workloads-18-19/ https://v1-9.docs.kubernetes.io/docs/reference/workloads-18-19/ 301

0 comments on commit f595b80

Please sign in to comment.