kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #22550 from tengqm/fix-links-contrib 

Tidy up: fix bad links in contribution guide
This commit is contained in:
Kubernetes Prow Robot 2020-07-20 18:21:13 -07:00 committed by GitHub
parent 0b05abd324 139da7d731
commit 1a7e81f77e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
18 changed files with 336 additions and 276 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
content/en/docs/contribute/_index.md
View File

@ -28,41 +28,62 @@ Kubernetes documentation welcomes improvements from all contributors, new and ex
## Getting started ## Getting started
Anyone can open an issue about documentation, or contribute a change with a pull request (PR) to the [`kubernetes/website` GitHub repository](https://github.com/kubernetes/website). You need to be comfortable with [git](https://git-scm.com/) and [GitHub](https://lab.github.com/) to operate effectively in the Kubernetes community. Anyone can open an issue about documentation, or contribute a change with a
pull request (PR) to the
[`kubernetes/website` GitHub repository](https://github.com/kubernetes/website).
You need to be comfortable with
[git](https://git-scm.com/) and
[GitHub](https://lab.github.com/)
to work effectively in the Kubernetes community.
To get involved with documentation: To get involved with documentation:
1. Sign the CNCF [Contributor License Agreement](https://github.com/kubernetes/community/blob/master/CLA.md). 1. Sign the CNCF [Contributor License Agreement](https://github.com/kubernetes/community/blob/master/CLA.md).
2. Familiarize yourself with the [documentation repository](https://github.com/kubernetes/website) and the website's [static site generator](https://gohugo.io). 1. Familiarize yourself with the [documentation repository](https://github.com/kubernetes/website)
3. Make sure you understand the basic processes for [opening a pull request](/docs/contribute/new-content/new-content/) and [reviewing changes](/docs/contribute/review/reviewing-prs/). and the website's [static site generator](https://gohugo.io).
1. Make sure you understand the basic processes for
[opening a pull request](/docs/contribute/new-content/open-a-pr/) and
[reviewing changes](/docs/contribute/review/reviewing-prs/).
Some tasks require more trust and more access in the Kubernetes organization. Some tasks require more trust and more access in the Kubernetes organization.
See [Participating in SIG Docs](/docs/contribute/participating/) for more details about See [Participating in SIG Docs](/docs/contribute/participate/) for more details about
roles and permissions. roles and permissions.
## Your first contribution ## Your first contribution
- Read the [Contribution overview](/docs/contribute/new-content/overview/) to learn about the different ways you can contribute. - Read the [Contribution overview](/docs/contribute/new-content/overview/) to
- See [Contribute to kubernetes/website](https://github.com/kubernetes/website/contribute) to find issues that make good entry points. learn about the different ways you can contribute.
- [Open a pull request using GitHub](/docs/contribute/new-content/new-content/#changes-using-github) to existing documentation and learn more about filing issues in GitHub. - Check [kubernetes/website issues list](/https://github.com/kubernetes/website/issues/)
- [Review pull requests](/docs/contribute/review/reviewing-prs/) from other Kubernetes community members for accuracy and language. for issues that make good entry points.
- Read the Kubernetes [content](/docs/contribute/style/content-guide/) and [style guides](/docs/contribute/style/style-guide/) so you can leave informed comments. - [Open a pull request using GitHub](/docs/contribute/new-content/open-a-pr/#changes-using-github)
- Learn about [page content types](/docs/contribute/style/page-content-types/) and [Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/). to existing documentation and learn more about filing issues in GitHub.
- [Review pull requests](/docs/contribute/review/reviewing-prs/) from other
Kubernetes community members for accuracy and language.
- Read the Kubernetes [content](/docs/contribute/style/content-guide/) and
[style guides](/docs/contribute/style/style-guide/) so you can leave informed comments.
- Learn about [page content types](/docs/contribute/style/page-content-types/)
and [Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/).
## Next steps ## Next steps
- Learn to [work from a local clone](/docs/contribute/new-content/new-content/#fork-the-repo) of the repository. - Learn to [work from a local clone](/docs/contribute/new-content/open-a-pr/#fork-the-repo)
of the repository.
- Document [features in a release](/docs/contribute/new-content/new-features/). - Document [features in a release](/docs/contribute/new-content/new-features/).
- Participate in [SIG Docs](/docs/contribute/participating/), and become a [member or reviewer](/docs/contribute/participating/#roles-and-responsibilities). - Participate in [SIG Docs](/docs/contribute/participate/), and become a
[member or reviewer](/docs/contribute/participate/roles-and-responsibilities/).
- Start or help with a [localization](/docs/contribute/localization/). - Start or help with a [localization](/docs/contribute/localization/).
## Get involved with SIG Docs ## Get involved with SIG Docs
[SIG Docs](/docs/contribute/participating/) is the group of contributors who publish and maintain Kubernetes documentation and the website. Getting involved with SIG Docs is a great way for Kubernetes contributors (feature development or otherwise) to have a large impact on the Kubernetes project. [SIG Docs](/docs/contribute/participate/) is the group of contributors who
publish and maintain Kubernetes documentation and the website. Getting
involved with SIG Docs is a great way for Kubernetes contributors (feature
development or otherwise) to have a large impact on the Kubernetes project.
SIG Docs communicates with different methods: SIG Docs communicates with different methods:
- [Join `#sig-docs` on the Kubernetes Slack instance](http://slack.k8s.io/). Make sure to - [Join `#sig-docs` on the Kubernetes Slack instance](https://slack.k8s.io/). Make sure to
introduce yourself! introduce yourself!
- [Join the `kubernetes-sig-docs` mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs), - [Join the `kubernetes-sig-docs` mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs),
where broader discussions take place and official decisions are recorded. where broader discussions take place and official decisions are recorded.

33
content/en/docs/contribute/advanced.md
View File

@ -13,13 +13,12 @@ This page assumes that you understand how to
to learn about more ways to contribute. You need to use the Git command line to learn about more ways to contribute. You need to use the Git command line
client and other tools for some of these tasks. client and other tools for some of these tasks.
<!-- body --> <!-- body -->
## Propose improvements ## Propose improvements
SIG Docs [members](/docs/contribute/participating/#members) can propose improvements. SIG Docs [members](/docs/contribute/participate/roles-and-responsibilities/#members)
can propose improvements.
After you've been contributing to the Kubernetes documentation for a while, you After you've been contributing to the Kubernetes documentation for a while, you
may have ideas for improving the [Style Guide](/docs/contribute/style/style-guide/) may have ideas for improving the [Style Guide](/docs/contribute/style/style-guide/)
@ -42,8 +41,8 @@ documentation testing might involve working with sig-testing.
## Coordinate docs for a Kubernetes release ## Coordinate docs for a Kubernetes release
SIG Docs [approvers](/docs/contribute/participating/#approvers) can coordinate SIG Docs [approvers](/docs/contribute/participate/roles-and-responsibilities/#approvers)
docs for a Kubernetes release. can coordinate docs for a Kubernetes release.
Each Kubernetes release is coordinated by a team of people participating in the Each Kubernetes release is coordinated by a team of people participating in the
sig-release Special Interest Group (SIG). Others on the release team for a given sig-release Special Interest Group (SIG). Others on the release team for a given
@ -73,8 +72,8 @@ rotated among SIG Docs approvers.
## Serve as a New Contributor Ambassador ## Serve as a New Contributor Ambassador
SIG Docs [approvers](/docs/contribute/participating/#approvers) can serve as SIG Docs [approvers](/docs/contribute/participate/roles-and-responsibilities/#approvers)
New Contributor Ambassadors. can serve as New Contributor Ambassadors.
New Contributor Ambassadors welcome new contributors to SIG-Docs, New Contributor Ambassadors welcome new contributors to SIG-Docs,
suggest PRs to new contributors, and mentor new contributors through their first suggest PRs to new contributors, and mentor new contributors through their first
@ -92,14 +91,14 @@ Current New Contributor Ambassadors are announced at each SIG-Docs meeting, and
## Sponsor a new contributor ## Sponsor a new contributor
SIG Docs [reviewers](/docs/contribute/participating/#reviewers) can sponsor SIG Docs [reviewers](/docs/contribute/participate/roles-and-responsibilities/#reviewers)
new contributors. can sponsor new contributors.
After a new contributor has successfully submitted 5 substantive pull requests After a new contributor has successfully submitted 5 substantive pull requests
to one or more Kubernetes repositories, they are eligible to apply for to one or more Kubernetes repositories, they are eligible to apply for
[membership](/docs/contribute/participating#members) in the Kubernetes [membership](/docs/contribute/participate/roles-and-responsibilities/#members)
organization. The contributor's membership needs to be backed by two sponsors in the Kubernetes organization. The contributor's membership needs to be
who are already reviewers. backed by two sponsors who are already reviewers.
New docs contributors can request sponsors by asking in the #sig-docs channel New docs contributors can request sponsors by asking in the #sig-docs channel
on the [Kubernetes Slack instance](https://kubernetes.slack.com) or on the on the [Kubernetes Slack instance](https://kubernetes.slack.com) or on the
@ -111,7 +110,8 @@ membership in the Kubernetes organization.
## Serve as a SIG Co-chair ## Serve as a SIG Co-chair
SIG Docs [approvers](/docs/contribute/participating/#approvers) can serve a term as a co-chair of SIG Docs. SIG Docs [approvers](/docs/contribute/participate/roles-and-responsibilities/#approvers)
can serve a term as a co-chair of SIG Docs.
### Prerequisites ### Prerequisites
@ -120,7 +120,12 @@ Approvers must meet the following requirements to be a co-chair:
- Have been a SIG Docs approver for at least 6 months - Have been a SIG Docs approver for at least 6 months
- Have [led a Kubernetes docs release](/docs/contribute/advanced/#coordinate-docs-for-a-kubernetes-release) or shadowed two releases - Have [led a Kubernetes docs release](/docs/contribute/advanced/#coordinate-docs-for-a-kubernetes-release) or shadowed two releases
- Understand SIG Docs workflows and tooling: git, Hugo, localization, blog subproject - Understand SIG Docs workflows and tooling: git, Hugo, localization, blog subproject
- Understand how other Kubernetes SIGs and repositories affect the SIG Docs workflow, including: [teams in k/org](https://github.com/kubernetes/org/blob/master/config/kubernetes/sig-docs/teams.yaml), [process in k/community](https://github.com/kubernetes/community/tree/master/sig-docs), plugins in [k/test-infra](https://github.com/kubernetes/test-infra/), and the role of [SIG Architecture](https://github.com/kubernetes/community/tree/master/sig-architecture). - Understand how other Kubernetes SIGs and repositories affect the SIG Docs
workflow, including:
[teams in k/org](https://github.com/kubernetes/org/blob/master/config/kubernetes/sig-docs/teams.yaml),
[process in k/community](https://github.com/kubernetes/community/tree/master/sig-docs),
plugins in [k/test-infra](https://github.com/kubernetes/test-infra/), and the role of
[SIG Architecture](https://github.com/kubernetes/community/tree/master/sig-architecture).
- Commit at least 5 hours per week (and often more) to the role for a minimum of 6 months - Commit at least 5 hours per week (and often more) to the role for a minimum of 6 months
### Responsibilities ### Responsibilities

9
content/en/docs/contribute/generate-ref-docs/kubectl.md
View File

@ -15,21 +15,16 @@ like
[kubectl apply](/docs/reference/generated/kubectl/kubectl-commands#apply) and [kubectl apply](/docs/reference/generated/kubectl/kubectl-commands#apply) and
[kubectl taint](/docs/reference/generated/kubectl/kubectl-commands#taint). [kubectl taint](/docs/reference/generated/kubectl/kubectl-commands#taint).
This topic does not show how to generate the This topic does not show how to generate the
[kubectl](/docs/reference/generated/kubectl/kubectl/) [kubectl](/docs/reference/generated/kubectl/kubectl-commands/)
options reference page. For instructions on how to generate the kubectl options options reference page. For instructions on how to generate the kubectl options
reference page, see reference page, see
[Generating Reference Pages for Kubernetes Components and Tools](/docs/home/contribute/generated-reference/kubernetes-components/). [Generating Reference Pages for Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/).
{{< /note >}} {{< /note >}}
## {{% heading "prerequisites" %}} ## {{% heading "prerequisites" %}}
{{< include "prerequisites-ref-docs.md" >}} {{< include "prerequisites-ref-docs.md" >}}
<!-- steps --> <!-- steps -->
## Setting up the local repositories ## Setting up the local repositories

4
content/en/docs/contribute/generate-ref-docs/kubernetes-api.md
View File

@ -194,16 +194,14 @@ The use of `make docker-serve` is deprecated. Please use `make container-serve`
In `<web-base>` run `git add` and `git commit` to commit the change. In `<web-base>` run `git add` and `git commit` to commit the change.
Submit your changes as a Submit your changes as a
[pull request](/docs/contribute/start/) to the [pull request](/docs/contribute/new-content/open-a-pr/) to the
[kubernetes/website](https://github.com/kubernetes/website) repository. [kubernetes/website](https://github.com/kubernetes/website) repository.
Monitor your pull request, and respond to reviewer comments as needed. Continue Monitor your pull request, and respond to reviewer comments as needed. Continue
to monitor your pull request until it has been merged. to monitor your pull request until it has been merged.
## {{% heading "whatsnext" %}} ## {{% heading "whatsnext" %}}
* [Generating Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/) * [Generating Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/)
* [Generating Reference Docs for Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/) * [Generating Reference Docs for Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/)
* [Generating Reference Documentation for kubectl Commands](/docs/contribute/generate-ref-docs/kubectl/) * [Generating Reference Documentation for kubectl Commands](/docs/contribute/generate-ref-docs/kubectl/)

3
content/en/docs/contribute/generate-ref-docs/prerequisites-ref-docs.md
View File

@ -18,4 +18,5 @@
- You need to know how to create a pull request to a GitHub repository. - You need to know how to create a pull request to a GitHub repository.
This involves creating your own fork of the repository. For more This involves creating your own fork of the repository. For more
information, see [Work from a local clone](/docs/contribute/intermediate/#work_from_a_local_clone). information, see [Work from a local clone](/docs/contribute/new-content/open-a-pr/#fork-the-repo).

7
content/en/docs/contribute/generate-ref-docs/quickstart.md
View File

@ -10,15 +10,10 @@ This page shows how to use the `update-imported-docs` script to generate
the Kubernetes reference documentation. The script automates the Kubernetes reference documentation. The script automates
the build setup and generates the reference documentation for a release. the build setup and generates the reference documentation for a release.
## {{% heading "prerequisites" %}} ## {{% heading "prerequisites" %}}
{{< include "prerequisites-ref-docs.md" >}} {{< include "prerequisites-ref-docs.md" >}}
<!-- steps --> <!-- steps -->
## Getting the docs repository ## Getting the docs repository
@ -87,7 +82,7 @@ The `update-imported-docs` script performs the following steps:
the sections in the `kubectl` command reference. the sections in the `kubectl` command reference.
When the generated files are in your local clone of the `<web-base>` When the generated files are in your local clone of the `<web-base>`
repository, you can submit them in a [pull request](/docs/contribute/start/) repository, you can submit them in a [pull request](/docs/contribute/new-content/open-a-pr/)
to `<web-base>`. to `<web-base>`.
## Configuration file format ## Configuration file format

2
content/en/docs/contribute/localization.md
View File

@ -183,7 +183,7 @@ Description | URLs
-----|----- -----|-----
Home | [All heading and subheading URLs](/docs/home/) Home | [All heading and subheading URLs](/docs/home/)
Setup | [All heading and subheading URLs](/docs/setup/) Setup | [All heading and subheading URLs](/docs/setup/)
Tutorials | [Kubernetes Basics](/docs/tutorials/kubernetes-basics/), [Hello Minikube](/docs/tutorials/stateless-application/hello-minikube/) Tutorials | [Kubernetes Basics](/docs/tutorials/kubernetes-basics/), [Hello Minikube](/docs/tutorials/hello-minikube/)
Site strings | [All site strings in a new localized TOML file](https://github.com/kubernetes/website/tree/master/i18n) Site strings | [All site strings in a new localized TOML file](https://github.com/kubernetes/website/tree/master/i18n)
Translated documents must reside in their own `content/**/` subdirectory, but otherwise follow the same URL path as the English source. For example, to prepare the [Kubernetes Basics](/docs/tutorials/kubernetes-basics/) tutorial for translation into German, create a subfolder under the `content/de/` folder and copy the English source: Translated documents must reside in their own `content/**/` subdirectory, but otherwise follow the same URL path as the English source. For example, to prepare the [Kubernetes Basics](/docs/tutorials/kubernetes-basics/) tutorial for translation into German, create a subfolder under the `content/de/` folder and copy the English source:

8
content/en/docs/contribute/new-content/overview.md
View File

@ -20,8 +20,12 @@ This section contains information you should know before contributing new conten
- Write Kubernetes documentation in Markdown and build the Kubernetes site using [Hugo](https://gohugo.io/). - Write Kubernetes documentation in Markdown and build the Kubernetes site using [Hugo](https://gohugo.io/).
- The source is in [GitHub](https://github.com/kubernetes/website). You can find Kubernetes documentation at `/content/en/docs/`. Some of the reference documentation is automatically generated from scripts in the `update-imported-docs/` directory. - The source is in [GitHub](https://github.com/kubernetes/website). You can find Kubernetes documentation at `/content/en/docs/`. Some of the reference documentation is automatically generated from scripts in the `update-imported-docs/` directory.
- [Page content types](/docs/contribute/style/page-content-types/) describe the presentation of documentation content in Hugo. - [Page content types](/docs/contribute/style/page-content-types/) describe the presentation of documentation content in Hugo.
- In addition to the standard Hugo shortcodes, we use a number of [custom Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/) in our documentation to control the presentation of content. - In addition to the standard Hugo shortcodes, we use a number of
- Documentation source is available in multiple languages in `/content/`. Each language has its own folder with a two-letter code determined by the [ISO 639-1 standard](https://www.loc.gov/standards/iso639-2/php/code_list.php). For example, English documentation source is stored in `/content/en/docs/`. [custom Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/) in our documentation to control the presentation of content.
- Documentation source is available in multiple languages in `/content/`. Each
language has its own folder with a two-letter code determined by the
[ISO 639-1 standard](https://www.loc.gov/standards/iso639-2/php/code_list.php). For
example, English documentation source is stored in `/content/en/docs/`.
- For more information about contributing to documentation in multiple languages or starting a new translation, see [localization](/docs/contribute/localization). - For more information about contributing to documentation in multiple languages or starting a new translation, see [localization](/docs/contribute/localization).
## Before you begin {#before-you-begin} ## Before you begin {#before-you-begin}

19
content/en/docs/contribute/participate/_index.md
View File

@ -20,18 +20,18 @@ 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 pull request (PR), and anyone is welcome to file issues about content or comment
on pull requests in progress. on pull requests in progress.
You can also become a [member](/docs/contribute/participating/roles-and-responsibilities/#members), You can also become a [member](/docs/contribute/participate/roles-and-responsibilities/#members),
[reviewer](/docs/contribute/participating/roles-and-responsibilities/#reviewers), or [approver](/docs/contribute/participating/roles-and-responsibilities/#approvers). These roles require greater [reviewer](/docs/contribute/participate/roles-and-responsibilities/#reviewers), or
access and entail certain responsibilities for approving and committing changes. [approver](/docs/contribute/participate/roles-and-responsibilities/#approvers).
See [community-membership](https://github.com/kubernetes/community/blob/master/community-membership.md) These roles require greater access and entail certain responsibilities for
approving and committing changes. See
[community-membership](https://github.com/kubernetes/community/blob/master/community-membership.md)
for more information on how membership works within the Kubernetes community. for more information on how membership works within the Kubernetes community.
The rest of this document outlines some unique ways these roles function within 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 SIG Docs, which is responsible for maintaining one of the most public-facing
aspects of Kubernetes -- the Kubernetes website and documentation. aspects of Kubernetes -- the Kubernetes website and documentation.
<!-- body --> <!-- body -->
## SIG Docs chairperson ## SIG Docs chairperson
@ -58,8 +58,9 @@ There are two categories of SIG Docs [teams](https://github.com/orgs/kubernetes/
Each can be referenced with their `@name` in GitHub comments to communicate with Each can be referenced with their `@name` in GitHub comments to communicate with
everyone in that group. everyone in that group.
Sometimes Prow and GitHub teams overlap without matching exactly. For assignment of issues, pull requests, and to support PR approvals, Sometimes Prow and GitHub teams overlap without matching exactly. For
the automation uses information from `OWNERS` files. assignment of issues, pull requests, and to support PR approvals, the
automation uses information from `OWNERS` files.
### OWNERS files and front-matter ### OWNERS files and front-matter
@ -114,6 +115,6 @@ SIG Docs approvers. Here's how it works.
For more information about contributing to the Kubernetes documentation, see: For more information about contributing to the Kubernetes documentation, see:
- [Contributing new content](/docs/contribute/overview/) - [Contributing new content](/docs/contribute/new-content/overview/)
- [Reviewing content](/docs/contribute/review/reviewing-prs) - [Reviewing content](/docs/contribute/review/reviewing-prs)
- [Documentation style guide](/docs/contribute/style/) - [Documentation style guide](/docs/contribute/style/)

237
content/en/docs/contribute/participate/roles-and-responsibilities.md Normal file
View File

@ -0,0 +1,237 @@
---
title: Roles and responsibilities
content_type: concept
weight: 10
---
<!-- overview -->
Anyone can contribute to Kubernetes. As your contributions to SIG Docs grow,
you can apply for different levels of membership in the community.
These roles allow you to take on more responsibility within the community.
Each role requires more time and commitment. The roles are:
- Anyone: regular contributors to the Kubernetes documentation
- Members: can assign and triage issues and provide non-binding review on pull requests
- Reviewers: can lead reviews on documentation pull requests and can vouch for a change's quality
- Approvers: can lead reviews on documentation and merge changes
<!-- body -->
## Anyone
Anyone with a GitHub account can contribute to Kubernetes. SIG Docs welcomes all new contributors!
Anyone can:
- Open an issue in any [Kubernetes](https://github.com/kubernetes/)
repository, including
[`kubernetes/website`](https://github.com/kubernetes/website)
- Give non-binding feedback on a pull request
- Contribute to a localization
- Suggest improvements on [Slack](https://slack.k8s.io/) or the
[SIG docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs).
After [signing the CLA](/docs/contribute/new-content/overview/#sign-the-cla), anyone can also:
- Open a pull request to improve existing content, add new content, or write a blog post or case study
- Create diagrams, graphics assets, and embeddable screencasts and videos
For more information, see [contributing new content](/docs/contribute/new-content/).
## Members
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).
Members can:
- Do everything listed under [Anyone](#anyone)
- Use the `/lgtm` comment to add the LGTM (looks good to me) label to a pull request
{{< note >}}
Using `/lgtm` triggers automation. If you want to provide non-binding
approval, simply commenting "LGTM" works too!
{{< /note >}}
- Use the `/hold` comment to block merging for a pull request
- Use the `/assign` comment to assign a reviewer to a pull request
- Provide non-binding review on pull requests
- Use automation to triage and categorize issues
- Document new features
### Becoming a member
After submitting at least 5 substantial pull requests and meeting the other
[requirements](https://github.com/kubernetes/community/blob/master/community-membership.md#member):
1. Find two [reviewers](#reviewers) or [approvers](#approvers) to
[sponsor](/docs/contribute/advanced#sponsor-a-new-contributor) your
membership.
Ask for sponsorship in the [#sig-docs channel on Slack](https://kubernetes.slack.com) or on the
[SIG Docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs).
{{< note >}}
Don't send a direct email or Slack direct message to an individual
SIG Docs member. You must request sponsorship before submitting your application.
{{< /note >}}
1. Open a GitHub issue in the
[`kubernetes/org`](https://github.com/kubernetes/org/) repository. Use the
**Organization Membership Request** issue template.
1. Let your sponsors know about the GitHub issue. You can either:
- Mention their GitHub username in an issue (`@<GitHub-username>`)
- Send them the issue link using Slack or email.
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!
If your membership request is not accepted you will receive feedback.
After addressing the feedback, apply again.
1. Accept the invitation to the Kubernetes GitHub organization in your email account.
{{< note >}}
GitHub sends the invitation to the default email address in your account.
{{< /note >}}
## Reviewers
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.
Reviewers can:
- Do everything listed under [Anyone](#anyone) and [Members](#members)
- Review pull requests and provide binding feedback
{{< note >}}
To provide non-binding feedback, prefix your comments with a phrase like "Optionally: ".
{{< /note >}}
- Edit user-facing strings in code
- Improve code comments
You can be a SIG Docs reviewer, or a reviewer for docs in a specific subject area.
### Assigning reviewers to pull requests
Automation assigns reviewers to all pull requests. You can request a
review from a specific person by commenting: `/assign
[@_github_handle]`.
If the assigned reviewer has not commented on the PR, another reviewer can
step in. You can also assign technical reviewers as needed.
### Using `/lgtm`
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.
A `/lgtm` comment from reviewer is binding and triggers automation that adds the `lgtm` label.
### Becoming a reviewer
When you meet the
[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.
To apply:
1. Open a pull request that adds your GitHub user name to a section of the
[OWNERS_ALIASES](https://github.com/kubernetes/website/blob/master/OWNERS) file
in the `kubernetes/website` repository.
{{< note >}}
If you aren't sure where to add yourself, add yourself to `sig-docs-en-reviews`.
{{< /note >}}
1. Assign the PR to one or more SIG-Docs approvers (user names listed under
`sig-docs-{language}-owners`).
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.
## Approvers
Approvers review and approve pull requests for merging. Approvers are members of the
[@kubernetes/sig-docs-{language}-owners](https://github.com/orgs/kubernetes/teams/?query=sig-docs)
GitHub teams.
Approvers can do the following:
- Everything listed under [Anyone](#anyone), [Members](#members) and [Reviewers](#reviewers)
- Publish contributor content by approving and merging pull requests using the `/approve` comment
- Propose improvements to the style guide
- Propose improvements to docs tests
- Propose improvements to the Kubernetes website or other tooling
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.
### Approving pull requests
Approvers and SIG Docs leads are the only ones who can merge pull requests
into the website repository. This comes with certain responsibilities.
- Approvers can use the `/approve` command, which merges PRs into the repo.
{{< warning >}}
A careless merge can break the site, so be sure that when you merge something, you mean it.
{{< /warning >}}
- Make sure that proposed changes meet the
[contribution guidelines](/docs/contribute/style/content-guide/#contributing-content).
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.
<img src="/images/docs/contribute/netlify-pass.png" width="75%" alt="Netlify tests must pass before approving" />
- Visit the Netlify page preview for a PR to make sure things look good before approving.
- 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
rotation. See [PR wranglers](/docs/contribute/participate/pr-wranglers/).
for more details.
### Becoming an approver
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.
To apply:
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.
{{< note >}}
If you aren't sure where to add yourself, add yourself to `sig-docs-en-owners`.
{{< /note >}}
2. Assign the PR to one or more current SIG Docs approvers.
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.
## {{% heading "whatsnext" %}}
- Read about [PR wrangling](/docs/contribute/participate/pr-wranglers/), a role all approvers take on rotation.

195
content/en/docs/contribute/participate/roles-and-responsibilties.md
View File

@ -1,195 +0,0 @@
---
title: Roles and responsibilities
content_type: concept
weight: 10
---
<!-- overview -->
Anyone can contribute to Kubernetes. As your contributions to SIG Docs grow, you can apply for different levels of membership in the community.
These roles allow you to take on more responsibility within the community.
Each role requires more time and commitment. The roles are:
- Anyone: regular contributors to the Kubernetes documentation
- Members: can assign and triage issues and provide non-binding review on pull requests
- Reviewers: can lead reviews on documentation pull requests and can vouch for a change's quality
- Approvers: can lead reviews on documentation and merge changes
<!-- body -->
## Anyone
Anyone with a GitHub account can contribute to Kubernetes. SIG Docs welcomes all new contributors!
Anyone can:
- Open an issue in any [Kubernetes](https://github.com/kubernetes/) repository, including [`kubernetes/website`](https://github.com/kubernetes/website)
- Give non-binding feedback on a pull request
- Contribute to a localization
- Suggest improvements on [Slack](http://slack.k8s.io/) or the [SIG docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs).
After [signing the CLA](/docs/contribute/new-content/overview/#sign-the-cla), anyone can also:
- Open a pull request to improve existing content, add new content, or write a blog post or case study
- Create diagrams, graphics assets, and embeddable screencasts and videos
For more information, see [contributing new content](/docs/contribute/new-content/).
## Members
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).
Members can:
- Do everything listed under [Anyone](#anyone)
- Use the `/lgtm` comment to add the LGTM (looks good to me) label to a pull request
{{< note >}}
Using `/lgtm` triggers automation. If you want to provide non-binding approval, simply commenting "LGTM" works too!
{{< /note >}}
- Use the `/hold` comment to block merging for a pull request
- Use the `/assign` comment to assign a reviewer to a pull request
- Provide non-binding review on pull requests
- Use automation to triage and categorize issues
- Document new features
### Becoming a member
After submitting at least 5 substantial pull requests and meeting the other [requirements](https://github.com/kubernetes/community/blob/master/community-membership.md#member):
1. Find two [reviewers](#reviewers) or [approvers](#approvers) to [sponsor](/docs/contribute/advanced#sponsor-a-new-contributor) your membership.
Ask for sponsorship in the [#sig-docs channel on Slack](https://kubernetes.slack.com) or on the
[SIG Docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs).
{{< note >}}
Don't send a direct email or Slack direct message to an individual
SIG Docs member. You must request sponsorship before submitting your application.
{{< /note >}}
2. Open a GitHub issue in the [`kubernetes/org`](https://github.com/kubernetes/org/) repository. Use the **Organization Membership Request** issue template.
3. Let your sponsors know about the GitHub issue. You can either:
- Mention their GitHub username in an issue (`@<GitHub-username>`)
- Send them the issue link using Slack or email.
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!
If your membership request is not accepted you will receive feedback. After addressing the feedback, apply again.
4. Accept the invitation to the Kubernetes GitHub organization in your email account.
{{< note >}}
GitHub sends the invitation to the default email address in your account.
{{< /note >}}
## Reviewers
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.
Reviewers can:
- Do everything listed under [Anyone](#anyone) and [Members](#members)
- Review pull requests and provide binding feedback
{{< note >}}
To provide non-binding feedback, prefix your comments with a phrase like "Optionally: ".
{{< /note >}}
- Edit user-facing strings in code
- Improve code comments
You can be a SIG Docs reviewer, or a reviewer for docs in a specific subject area.
### Assigning reviewers to pull requests
Automation assigns reviewers to all pull requests. You can request a
review from a specific person by commenting: `/assign
[@_github_handle]`.
If the assigned reviewer has not commented on the PR, another reviewer can step in. You can also assign technical reviewers as needed.
### Using `/lgtm`
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.
A `/lgtm` comment from reviewer is binding and triggers automation that adds the `lgtm` label.
### Becoming a reviewer
When you meet the
[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.
To apply:
1. Open a pull request that adds your GitHub user name to a section of the
[OWNERS_ALIASES](https://github.com/kubernetes/website/blob/master/OWNERS) file
in the `kubernetes/website` repository.
{{< note >}}
If you aren't sure where to add yourself, add yourself to `sig-docs-en-reviews`.
{{< /note >}}
2. Assign the PR to one or more SIG-Docs approvers (user names listed under `sig-docs-{language}-owners`).
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.
## Approvers
Approvers review and approve pull requests for merging. Approvers are members of the
[@kubernetes/sig-docs-{language}-owners](https://github.com/orgs/kubernetes/teams/?query=sig-docs) GitHub teams.
Approvers can do the following:
- Everything listed under [Anyone](#anyone), [Members](#members) and [Reviewers](#reviewers)
- Publish contributor content by approving and merging pull requests using the `/approve` comment
- Propose improvements to the style guide
- Propose improvements to docs tests
- Propose improvements to the Kubernetes website or other tooling
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.
### Approving pull requests
Approvers and SIG Docs leads are the only ones who can merge pull requests into the website repository. This comes with certain responsibilities.
- Approvers can use the `/approve` command, which merges PRs into the repo.
{{< warning >}}
A careless merge can break the site, so be sure that when you merge something, you mean it.
{{< /warning >}}
- Make sure that proposed changes meet the [contribution guidelines](/docs/contribute/style/content-guide/#contributing-content).
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.
<img src="/images/docs/contribute/netlify-pass.png" width="75%" alt="Netlify tests must pass before approving" />
- Visit the Netlify page preview for a PR to make sure things look good before approving.
- 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
rotation. See [PR wranglers](/docs/contribute/participating/pr-wranglers/).
for more details.
### Becoming an approver
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.
To apply:
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.
{{< note >}}
If you aren't sure where to add yourself, add yourself to `sig-docs-en-owners`.
{{< /note >}}
2. Assign the PR to one or more current SIG Docs approvers.
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.
## {{% heading "whatsnext" %}}
- Read about [PR wrangling](/docs/contribute/participating/pr-wranglers), a role all approvers take on rotation.

11
content/en/docs/contribute/review/for-approvers.md
View File

@ -8,7 +8,9 @@ weight: 20
<!-- overview --> <!-- overview -->
SIG Docs [Reviewers](/docs/contribute/participating/#reviewers) and [Approvers](/docs/contribute/participating/#approvers) do a few extra things when reviewing a change. SIG Docs [Reviewers](/docs/contribute/participate/#reviewers) and
[Approvers](/docs/contribute/participate/#approvers) do a few extra things
when reviewing a change.
Every week a specific docs approver volunteers to triage Every week a specific docs approver volunteers to triage
and review pull requests. This and review pull requests. This
@ -19,9 +21,6 @@ requests (PRs) that are not already under active review.
In addition to the rotation, a bot assigns reviewers and approvers In addition to the rotation, a bot assigns reviewers and approvers
for the PR based on the owners for the affected files. for the PR based on the owners for the affected files.
<!-- body --> <!-- body -->
## Reviewing a PR ## Reviewing a PR
@ -202,9 +201,9 @@ Sample response to a request for support:
This issue sounds more like a request for support and less This issue sounds more like a request for support and less
like an issue specifically for docs. I encourage you to bring like an issue specifically for docs. I encourage you to bring
your question to the `#kubernetes-users` channel in your question to the `#kubernetes-users` channel in
[Kubernetes slack](http://slack.k8s.io/). You can also search [Kubernetes slack](https://slack.k8s.io/). You can also search
resources like resources like
[Stack Overflow](http://stackoverflow.com/questions/tagged/kubernetes) [Stack Overflow](https://stackoverflow.com/questions/tagged/kubernetes)
for answers to similar questions. for answers to similar questions.
You can also open issues for Kubernetes functionality in You can also open issues for Kubernetes functionality in

8
content/en/docs/contribute/review/reviewing-prs.md
View File

@ -16,10 +16,10 @@ It helps you learn the code base and build trust with other contributors.
Before reviewing, it's a good idea to: Before reviewing, it's a good idea to:
- Read the [content guide](/docs/contribute/style/content-guide/) and - Read the [content guide](/docs/contribute/style/content-guide/) and
[style guide](/docs/contribute/style/style-guide/) so you can leave informed comments. [style guide](/docs/contribute/style/style-guide/) so you can leave informed comments.
- Understand the different [roles and responsibilities](/docs/contribute/participating/#roles-and-responsibilities) in the Kubernetes documentation community. - Understand the different
[roles and responsibilities](/docs/contribute/participate/roles-and-responsibilities/)
in the Kubernetes documentation community.
<!-- body --> <!-- body -->

6
content/en/docs/contribute/style/content-guide.md
View File

@ -10,9 +10,9 @@ weight: 10
This page contains guidelines for Kubernetes documentation. This page contains guidelines for Kubernetes documentation.
If you have questions about what's allowed, join the #sig-docs channel in If you have questions about what's allowed, join the #sig-docs channel in
[Kubernetes Slack](http://slack.k8s.io/) and ask! [Kubernetes Slack](https://slack.k8s.io/) and ask!
You can register for Kubernetes Slack at http://slack.k8s.io/. You can register for Kubernetes Slack at https://slack.k8s.io/.
For information on creating new content for the Kubernetes For information on creating new content for the Kubernetes
docs, follow the [style guide](/docs/contribute/style/style-guide). docs, follow the [style guide](/docs/contribute/style/style-guide).
@ -67,7 +67,7 @@ ask for help in [#sig-docs on Kubernetes Slack](https://kubernetes.slack.com/mes
### More information ### More information
If you have questions about allowed content, join the [Kubernetes Slack](http://slack.k8s.io/) #sig-docs channel and ask! If you have questions about allowed content, join the [Kubernetes Slack](https://slack.k8s.io/) #sig-docs channel and ask!

4
content/en/docs/contribute/style/hugo-shortcodes/index.md
View File

@ -232,7 +232,7 @@ Renders to:
{{< tabs name="tab_with_file_include" >}} {{< tabs name="tab_with_file_include" >}}
{{< tab name="Content File #1" include="example1" />}} {{< tab name="Content File #1" include="example1" />}}
{{< tab name="Content File #2" include="example2" />}} {{< tab name="Content File #2" include="example2" />}}
{{< tab name="JSON File" include="podtemplate" />}} {{< tab name="JSON File" include="podtemplate.json" />}}
{{< /tabs >}} {{< /tabs >}}
@ -242,6 +242,6 @@ Renders to:
* Learn about [Hugo](https://gohugo.io/). * Learn about [Hugo](https://gohugo.io/).
* Learn about [writing a new topic](/docs/contribute/style/write-new-topic/). * Learn about [writing a new topic](/docs/contribute/style/write-new-topic/).
* Learn about [page content types](/docs/contribute/style/page-content-types/). * Learn about [page content types](/docs/contribute/style/page-content-types/).
* Learn about [creating a pull request](/docs/contribute/new-content/new-content/). * Learn about [opening a pull request](/docs/contribute/new-content/open-a-pr/).
* Learn about [advanced contributing](/docs/contribute/advanced/). * Learn about [advanced contributing](/docs/contribute/advanced/).

2
content/en/docs/contribute/style/page-content-types.md
View File

@ -191,7 +191,7 @@ Within each section, write your content. Use the following guidelines:
interested in reading next. interested in reading next.
An example of a published tutorial topic is An example of a published tutorial topic is
[Running a Stateless Application Using a Deployment](/docs/tutorials/stateless-application/run-stateless-application-deployment/). [Running a Stateless Application Using a Deployment](/docs/tasks/run-application/run-stateless-application-deployment/).
### Reference ### Reference

11
content/en/docs/contribute/style/style-guide.md
View File

@ -22,8 +22,11 @@ discussion.
<!-- body --> <!-- body -->
{{< note >}} {{< note >}}
Kubernetes documentation uses [Blackfriday Markdown Renderer](https://github.com/russross/blackfriday) along with a few [Hugo Shortcodes](/docs/home/contribute/includes/) to support glossary entries, tabs, Kubernetes documentation uses
and representing feature state. [Goldmark Markdown Renderer](https://github.com/yuin/goldmark)
with some adjustments along with a few
[Hugo Shortcodes](/docs/contribute/style/hugo-shortcodes/) to support
glossary entries, tabs, and representing feature state.
{{< /note >}} {{< /note >}}
## Language ## Language
@ -584,12 +587,8 @@ The Federation feature provides ... | The new Federation feature provides ...
{{< /table >}} {{< /table >}}
## {{% heading "whatsnext" %}} ## {{% heading "whatsnext" %}}
* Learn about [writing a new topic](/docs/contribute/style/write-new-topic/). * Learn about [writing a new topic](/docs/contribute/style/write-new-topic/).
* Learn about [using page templates](/docs/contribute/style/page-content-types/). * Learn about [using page templates](/docs/contribute/style/page-content-types/).
* Learn about [staging your changes](/docs/contribute/stage-documentation-changes/)
* Learn about [creating a pull request](/docs/contribute/new-content/open-a-pr/). * Learn about [creating a pull request](/docs/contribute/new-content/open-a-pr/).

4
content/en/docs/contribute/style/write-new-topic.md
View File

@ -11,7 +11,7 @@ This page shows how to create a new topic for the Kubernetes docs.
## {{% heading "prerequisites" %}} ## {{% heading "prerequisites" %}}
Create a fork of the Kubernetes documentation repository as described in Create a fork of the Kubernetes documentation repository as described in
[Open a PR](/docs/new-content/open-a-pr/). [Open a PR](/docs/contribute/new-content/open-a-pr/).
<!-- steps --> <!-- steps -->
@ -160,7 +160,7 @@ submitted to ensure all examples pass the tests.
{{< /note >}} {{< /note >}}
For an example of a topic that uses this technique, see For an example of a topic that uses this technique, see
[Running a Single-Instance Stateful Application](/docs/tutorials/stateful-application/run-stateful-application/). [Running a Single-Instance Stateful Application](/docs/tasks/run-application/run-single-instance-stateful-application/).
## Adding images to a topic ## Adding images to a topic