diff --git a/content/en/docs/contribute/_index.md b/content/en/docs/contribute/_index.md index d8f57e5e82..cd1b03efd4 100644 --- a/content/en/docs/contribute/_index.md +++ b/content/en/docs/contribute/_index.md @@ -28,41 +28,62 @@ Kubernetes documentation welcomes improvements from all contributors, new and ex ## 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: 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). -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/). +1. Familiarize yourself with the [documentation repository](https://github.com/kubernetes/website) + 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. -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. ## Your first contribution -- Read the [Contribution overview](/docs/contribute/new-content/overview/) to learn about the different ways you can contribute. -- See [Contribute to kubernetes/website](https://github.com/kubernetes/website/contribute) to find issues that make good entry points. -- [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. -- [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/). +- Read the [Contribution overview](/docs/contribute/new-content/overview/) to + learn about the different ways you can contribute. +- Check [kubernetes/website issues list](/https://github.com/kubernetes/website/issues/) + for issues that make good entry points. +- [Open a pull request using GitHub](/docs/contribute/new-content/open-a-pr/#changes-using-github) + 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 -- 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/). -- 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/). ## 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: -- [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! - [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. diff --git a/content/en/docs/contribute/advanced.md b/content/en/docs/contribute/advanced.md index 44c72916d9..e50287842a 100644 --- a/content/en/docs/contribute/advanced.md +++ b/content/en/docs/contribute/advanced.md @@ -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 client and other tools for some of these tasks. - - ## 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 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 -SIG Docs [approvers](/docs/contribute/participating/#approvers) can coordinate -docs for a Kubernetes release. +SIG Docs [approvers](/docs/contribute/participate/roles-and-responsibilities/#approvers) +can coordinate docs for a Kubernetes release. 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 @@ -73,8 +72,8 @@ rotated among SIG Docs approvers. ## Serve as a New Contributor Ambassador -SIG Docs [approvers](/docs/contribute/participating/#approvers) can serve as -New Contributor Ambassadors. +SIG Docs [approvers](/docs/contribute/participate/roles-and-responsibilities/#approvers) +can serve as New Contributor Ambassadors. New Contributor Ambassadors welcome new contributors to SIG-Docs, 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 -SIG Docs [reviewers](/docs/contribute/participating/#reviewers) can sponsor -new contributors. +SIG Docs [reviewers](/docs/contribute/participate/roles-and-responsibilities/#reviewers) +can sponsor new contributors. After a new contributor has successfully submitted 5 substantive pull requests to one or more Kubernetes repositories, they are eligible to apply for -[membership](/docs/contribute/participating#members) in the Kubernetes -organization. The contributor's membership needs to be backed by two sponsors -who are already reviewers. +[membership](/docs/contribute/participate/roles-and-responsibilities/#members) +in the Kubernetes organization. The contributor's membership needs to be +backed by two sponsors who are already reviewers. 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 @@ -111,7 +110,8 @@ membership in the Kubernetes organization. ## 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 @@ -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 [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 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 ### Responsibilities @@ -183,4 +188,4 @@ When you’re ready to start the recording, click Record to Cloud. When you’re ready to stop recording, click Stop. -The video uploads automatically to YouTube. \ No newline at end of file +The video uploads automatically to YouTube. diff --git a/content/en/docs/contribute/generate-ref-docs/kubectl.md b/content/en/docs/contribute/generate-ref-docs/kubectl.md index a1fed1642e..ea6065472e 100644 --- a/content/en/docs/contribute/generate-ref-docs/kubectl.md +++ b/content/en/docs/contribute/generate-ref-docs/kubectl.md @@ -15,21 +15,16 @@ like [kubectl apply](/docs/reference/generated/kubectl/kubectl-commands#apply) and [kubectl taint](/docs/reference/generated/kubectl/kubectl-commands#taint). 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 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 >}} - - ## {{% heading "prerequisites" %}} - {{< include "prerequisites-ref-docs.md" >}} - - ## Setting up the local repositories diff --git a/content/en/docs/contribute/generate-ref-docs/kubernetes-api.md b/content/en/docs/contribute/generate-ref-docs/kubernetes-api.md index f68d81dfb4..f2ec01d8e8 100644 --- a/content/en/docs/contribute/generate-ref-docs/kubernetes-api.md +++ b/content/en/docs/contribute/generate-ref-docs/kubernetes-api.md @@ -194,16 +194,14 @@ The use of `make docker-serve` is deprecated. Please use `make container-serve` In `` run `git add` and `git commit` to commit the change. 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. Monitor your pull request, and respond to reviewer comments as needed. Continue to monitor your pull request until it has been merged. - ## {{% heading "whatsnext" %}} - * [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 Documentation for kubectl Commands](/docs/contribute/generate-ref-docs/kubectl/) diff --git a/content/en/docs/contribute/generate-ref-docs/prerequisites-ref-docs.md b/content/en/docs/contribute/generate-ref-docs/prerequisites-ref-docs.md index a777fb77e5..c719920813 100644 --- a/content/en/docs/contribute/generate-ref-docs/prerequisites-ref-docs.md +++ b/content/en/docs/contribute/generate-ref-docs/prerequisites-ref-docs.md @@ -18,4 +18,5 @@ - 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 - 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). + diff --git a/content/en/docs/contribute/generate-ref-docs/quickstart.md b/content/en/docs/contribute/generate-ref-docs/quickstart.md index df5cdbb95f..0790f7925a 100644 --- a/content/en/docs/contribute/generate-ref-docs/quickstart.md +++ b/content/en/docs/contribute/generate-ref-docs/quickstart.md @@ -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 build setup and generates the reference documentation for a release. - - ## {{% heading "prerequisites" %}} - {{< include "prerequisites-ref-docs.md" >}} - - ## Getting the docs repository @@ -87,7 +82,7 @@ The `update-imported-docs` script performs the following steps: the sections in the `kubectl` command reference. When the generated files are in your local clone of the `` -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 ``. ## Configuration file format diff --git a/content/en/docs/contribute/localization.md b/content/en/docs/contribute/localization.md index 0c698305b9..1ae4796522 100644 --- a/content/en/docs/contribute/localization.md +++ b/content/en/docs/contribute/localization.md @@ -183,7 +183,7 @@ Description | URLs -----|----- Home | [All heading and subheading URLs](/docs/home/) 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) 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: diff --git a/content/en/docs/contribute/new-content/overview.md b/content/en/docs/contribute/new-content/overview.md index e9ef332430..b1f7e4f20a 100644 --- a/content/en/docs/contribute/new-content/overview.md +++ b/content/en/docs/contribute/new-content/overview.md @@ -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/). - 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. -- 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. -- 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/`. +- 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. +- 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). ## Before you begin {#before-you-begin} diff --git a/content/en/docs/contribute/participate/_index.md b/content/en/docs/contribute/participate/_index.md index a99eaf464e..a5c0f2880a 100644 --- a/content/en/docs/contribute/participate/_index.md +++ b/content/en/docs/contribute/participate/_index.md @@ -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 on pull requests in progress. -You can also become a [member](/docs/contribute/participating/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 -access and entail certain responsibilities for approving and committing changes. -See [community-membership](https://github.com/kubernetes/community/blob/master/community-membership.md) +You can also become a [member](/docs/contribute/participate/roles-and-responsibilities/#members), +[reviewer](/docs/contribute/participate/roles-and-responsibilities/#reviewers), or +[approver](/docs/contribute/participate/roles-and-responsibilities/#approvers). +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. 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. - - ## 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 everyone in that group. -Sometimes Prow and GitHub teams overlap without matching exactly. For assignment of issues, pull requests, and to support PR approvals, -the automation uses information from `OWNERS` files. +Sometimes Prow and GitHub teams overlap without matching exactly. For +assignment of issues, pull requests, and to support PR approvals, the +automation uses information from `OWNERS` files. ### 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: -- [Contributing new content](/docs/contribute/overview/) +- [Contributing new content](/docs/contribute/new-content/overview/) - [Reviewing content](/docs/contribute/review/reviewing-prs) - [Documentation style guide](/docs/contribute/style/) diff --git a/content/en/docs/contribute/participate/roles-and-responsibilities.md b/content/en/docs/contribute/participate/roles-and-responsibilities.md new file mode 100644 index 0000000000..8ebe7a1303 --- /dev/null +++ b/content/en/docs/contribute/participate/roles-and-responsibilities.md @@ -0,0 +1,237 @@ +--- +title: Roles and responsibilities +content_type: concept +weight: 10 +--- + + + +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 + + + +## 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 (`@`) + - 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. + + 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. diff --git a/content/en/docs/contribute/participate/roles-and-responsibilties.md b/content/en/docs/contribute/participate/roles-and-responsibilties.md deleted file mode 100644 index f4cca67155..0000000000 --- a/content/en/docs/contribute/participate/roles-and-responsibilties.md +++ /dev/null @@ -1,195 +0,0 @@ ---- -title: Roles and responsibilities -content_type: concept -weight: 10 ---- - - - -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 - - - -## 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 (`@`) - - 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. - - 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. \ No newline at end of file diff --git a/content/en/docs/contribute/review/for-approvers.md b/content/en/docs/contribute/review/for-approvers.md index 0cddbcba6a..82a05bdb86 100644 --- a/content/en/docs/contribute/review/for-approvers.md +++ b/content/en/docs/contribute/review/for-approvers.md @@ -8,7 +8,9 @@ weight: 20 -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 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 for the PR based on the owners for the affected files. - - - ## 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 like an issue specifically for docs. I encourage you to bring 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 -[Stack Overflow](http://stackoverflow.com/questions/tagged/kubernetes) +[Stack Overflow](https://stackoverflow.com/questions/tagged/kubernetes) for answers to similar questions. You can also open issues for Kubernetes functionality in diff --git a/content/en/docs/contribute/review/reviewing-prs.md b/content/en/docs/contribute/review/reviewing-prs.md index 3c271aa44f..ff6ef9d709 100644 --- a/content/en/docs/contribute/review/reviewing-prs.md +++ b/content/en/docs/contribute/review/reviewing-prs.md @@ -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: - Read the [content guide](/docs/contribute/style/content-guide/) and -[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. - - + [style guide](/docs/contribute/style/style-guide/) so you can leave informed comments. +- Understand the different + [roles and responsibilities](/docs/contribute/participate/roles-and-responsibilities/) + in the Kubernetes documentation community. diff --git a/content/en/docs/contribute/style/content-guide.md b/content/en/docs/contribute/style/content-guide.md index 569ca8d72c..0de4a381a3 100644 --- a/content/en/docs/contribute/style/content-guide.md +++ b/content/en/docs/contribute/style/content-guide.md @@ -10,9 +10,9 @@ weight: 10 This page contains guidelines for Kubernetes documentation. 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 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 -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! diff --git a/content/en/docs/contribute/style/hugo-shortcodes/index.md b/content/en/docs/contribute/style/hugo-shortcodes/index.md index e4a6d703ad..ab949be7fc 100644 --- a/content/en/docs/contribute/style/hugo-shortcodes/index.md +++ b/content/en/docs/contribute/style/hugo-shortcodes/index.md @@ -232,7 +232,7 @@ Renders to: {{< tabs name="tab_with_file_include" >}} {{< tab name="Content File #1" include="example1" />}} {{< tab name="Content File #2" include="example2" />}} -{{< tab name="JSON File" include="podtemplate" />}} +{{< tab name="JSON File" include="podtemplate.json" />}} {{< /tabs >}} @@ -242,6 +242,6 @@ Renders to: * Learn about [Hugo](https://gohugo.io/). * 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 [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/). diff --git a/content/en/docs/contribute/style/page-content-types.md b/content/en/docs/contribute/style/page-content-types.md index 2a3325d397..5d3b519bc0 100644 --- a/content/en/docs/contribute/style/page-content-types.md +++ b/content/en/docs/contribute/style/page-content-types.md @@ -191,7 +191,7 @@ Within each section, write your content. Use the following guidelines: interested in reading next. 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 diff --git a/content/en/docs/contribute/style/style-guide.md b/content/en/docs/contribute/style/style-guide.md index 55aa30d66c..44653708ec 100644 --- a/content/en/docs/contribute/style/style-guide.md +++ b/content/en/docs/contribute/style/style-guide.md @@ -22,8 +22,11 @@ discussion. {{< 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, -and representing feature state. +Kubernetes documentation uses +[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 >}} ## Language @@ -584,12 +587,8 @@ The Federation feature provides ... | The new Federation feature provides ... {{< /table >}} - - ## {{% heading "whatsnext" %}} - * 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 [staging your changes](/docs/contribute/stage-documentation-changes/) * Learn about [creating a pull request](/docs/contribute/new-content/open-a-pr/). diff --git a/content/en/docs/contribute/style/write-new-topic.md b/content/en/docs/contribute/style/write-new-topic.md index 3e4f999c08..7cac1aa6b7 100644 --- a/content/en/docs/contribute/style/write-new-topic.md +++ b/content/en/docs/contribute/style/write-new-topic.md @@ -11,7 +11,7 @@ This page shows how to create a new topic for the Kubernetes docs. ## {{% heading "prerequisites" %}} 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/). @@ -160,7 +160,7 @@ submitted to ensure all examples pass the tests. {{< /note >}} 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