diff --git a/config.toml b/config.toml
index eba5852abb..0976ae205a 100644
--- a/config.toml
+++ b/config.toml
@@ -123,6 +123,7 @@ id = "UA-00000000-0"
[params]
copyright_k8s = "The Kubernetes Authors"
copyright_linux = "Copyright © 2020 The Linux Foundation ®."
+
# privacy_policy = "https://policies.google.com/privacy"
# First one is picked as the Twitter card image if not set on page.
diff --git a/content/en/docs/contribute/_index.md b/content/en/docs/contribute/_index.md
index 1db65ec56d..1042604550 100644
--- a/content/en/docs/contribute/_index.md
+++ b/content/en/docs/contribute/_index.md
@@ -29,6 +29,8 @@ Kubernetes documentation contributors:
- Translate the documentation
- Manage and publish the documentation parts of the Kubernetes release cycle
+
+
## Getting started
@@ -44,18 +46,98 @@ 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).
-1. Familiarize yourself with the [documentation repository](https://github.com/kubernetes/website)
+2. 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
+3. 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/).
+
+
+
+{{< mermaid >}}
+flowchart TB
+subgraph third[Open PR]
+direction TB
+U[ ] -.-
+Q[Improve content] --- N[Create content]
+N --- O[Translate docs]
+O --- P[Manage/publish docs parts
of K8s release cycle]
+
+end
+
+subgraph second[Review]
+direction TB
+ T[ ] -.-
+ D[Look over the
K8s/website
repository] --- E[Check out the
Hugo static site
generator]
+ E --- F[Understand basic
GitHub commands]
+ F --- G[Review open PR
and change review
processes]
+end
+
+subgraph first[Sign up]
+ direction TB
+ S[ ] -.-
+ B[Sign the CNCF
Contributor
License Agreement] --- C[Join sig-docs
Slack channel]
+ C --- V[Join kubernetes-sig-docs
mailing list]
+ V --- M[Attend weekly
sig-docs calls
or slack meetings]
+end
+
+A([fa:fa-user New
Contributor]) --> first
+A --> second
+A --> third
+A --> H[Ask Questions!!!]
+
+
+classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
+classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
+classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
+class A,B,C,D,E,F,G,H,M,Q,N,O,P,V grey
+class S,T,U spacewhite
+class first,second,third white
+{{ mermaid >}}
+***Figure - Getting started for a new contributor***
+
+The figure above outlines a roadmap for new contributors. You can follow some or all of the steps for `Sign up` and `Review`. Now you are ready to open PRs that achieve your contribution objectives with some listed under `Open PR`. Again, questions are always welcome!
+
Some tasks require more trust and more access in the Kubernetes organization.
See [Participating in SIG Docs](/docs/contribute/participate/) for more details about
roles and permissions.
## Your first contribution
+You can prepare for your first contribution by reviewing several steps beforehand. The figure below outlines the steps and the details follow.
+
+
+
+
+{{< mermaid >}}
+flowchart LR
+ subgraph second[First Contribution]
+ direction TB
+ S[ ] -.-
+ G[Review PRs from other
K8s members] -->
+ A[Check K8s/website
issues list for
good first PRs] --> B[Open a PR!!]
+ end
+ subgraph first[Suggested Prep]
+ direction TB
+ T[ ] -.-
+ D[Read contribution overview] -->E[Read K8s content
and style guides]
+ E --> F[Learn about Hugo page
content types
and shortcodes]
+ end
+
+
+ first ----> second
+
+
+classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
+classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
+classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
+class A,B,D,E,F,G grey
+class S,T spacewhite
+class first,second white
+{{ mermaid >}}
+***Figure - Preparation for your first contribution***
+
- 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/)
@@ -92,10 +174,12 @@ SIG Docs communicates with different methods:
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.
-- Join the [weekly SIG Docs video meeting](https://github.com/kubernetes/community/tree/master/sig-docs). Meetings are always announced on `#sig-docs` and added to the [Kubernetes community meetings calendar](https://calendar.google.com/calendar/embed?src=cgnt364vd8s86hr2phapfjc6uk%40group.calendar.google.com&ctz=America/Los_Angeles). You'll need to download the [Zoom client](https://zoom.us/download) or dial in using a phone.
+- Join the [SIG Docs video meeting](https://github.com/kubernetes/community/tree/master/sig-docs) held every two weeks. Meetings are always announced on `#sig-docs` and added to the [Kubernetes community meetings calendar](https://calendar.google.com/calendar/embed?src=cgnt364vd8s86hr2phapfjc6uk%40group.calendar.google.com&ctz=America/Los_Angeles). You'll need to download the [Zoom client](https://zoom.us/download) or dial in using a phone.
+- Join the SIG Docs async Slack standup meeting on those weeks when the in-person Zoom video meeting does not take place. Meetings are always announced on `#sig-docs`. You can contribute to any one of the threads up to 24 hours after meeting announcement.
## Other ways to contribute
- Visit the [Kubernetes community site](/community/). Participate on Twitter or Stack Overflow, learn about local Kubernetes meetups and events, and more.
- Read the [contributor cheatsheet](https://github.com/kubernetes/community/tree/master/contributors/guide/contributor-cheatsheet) to get involved with Kubernetes feature development.
- Submit a [blog post or case study](/docs/contribute/new-content/blogs-case-studies/).
+
diff --git a/content/en/docs/contribute/new-content/_index.md b/content/en/docs/contribute/new-content/_index.md
index 01677af0ed..501e417985 100644
--- a/content/en/docs/contribute/new-content/_index.md
+++ b/content/en/docs/contribute/new-content/_index.md
@@ -5,10 +5,48 @@ main_menu: true
weight: 20
---
+
+
-This section contains information you should know before contributing new content.
+This section contains information you should know before contributing new
+content.
+
+
+{{< mermaid >}}
+flowchart LR
+ subgraph second[Before you begin]
+ direction TB
+ S[ ] -.-
+ A[Sign the CNCF CLA] --> B[Choose Git branch]
+ B --> C[One language per PR]
+ C --> F[Check out
contributor tools]
+ end
+ subgraph first[Contributing Basics]
+ direction TB
+ T[ ] -.-
+ D[Write docs in markdown
and build site with Hugo] --- E[source in GitHub]
+ E --- G[_'/content/../docs'_ folder contains docs
for multiple languages]
+ G --- H[Review Hugo page content
types and shortcodes]
+ end
+
+
+ first ----> second
+
+
+classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
+classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
+classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
+class A,B,C,D,E,F,G,H grey
+class S,T spacewhite
+class first,second white
+{{ mermaid >}}
+
+***Figure - Contributing new content preparation***
+
+The figure above depicts the information you should know
+prior to submitting new content. The information details follow.
@@ -16,28 +54,43 @@ This section contains information you should know before contributing new conten
## Contributing basics
-- 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.
+- 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.
+ [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).
+ [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}
### Sign the CNCF CLA {#sign-the-cla}
-All Kubernetes contributors **must** read the [Contributor guide](https://github.com/kubernetes/community/blob/master/contributors/guide/README.md) and [sign the Contributor License Agreement (CLA)](https://github.com/kubernetes/community/blob/master/CLA.md).
+All Kubernetes contributors **must** read
+the [Contributor guide](https://github.com/kubernetes/community/blob/master/contributors/guide/README.md)
+and [sign the Contributor License Agreement (CLA)](https://github.com/kubernetes/community/blob/master/CLA.md)
+.
-Pull requests from contributors who haven't signed the CLA fail the automated tests. The name and email you provide must match those found in your `git config`, and your git name and email must match those used for the CNCF CLA.
+Pull requests from contributors who haven't signed the CLA fail the automated
+tests. The name and email you provide must match those found in
+your `git config`, and your git name and email must match those used for the
+CNCF CLA.
### Choose which Git branch to use
-When opening a pull request, you need to know in advance which branch to base your work on.
+When opening a pull request, you need to know in advance which branch to base
+your work on.
Scenario | Branch
:---------|:------------
@@ -45,20 +98,21 @@ Existing or new English language content for the current release | `main`
Content for a feature change release | The branch which corresponds to the major and minor version the feature change is in, using the pattern `dev-`. For example, if a feature changes in the `v{{< skew nextMinorVersion >}}` release, then add documentation changes to the ``dev-{{< skew nextMinorVersion >}}`` branch.
Content in other languages (localizations) | Use the localization's convention. See the [Localization branching strategy](/docs/contribute/localization/#branching-strategy) for more information.
-
If you're still not sure which branch to choose, ask in `#sig-docs` on Slack.
-{{< note >}}
-If you already submitted your pull request and you know that the base branch
-was wrong, you (and only you, the submitter) can change it.
-{{< /note >}}
+{{< note >}} If you already submitted your pull request and you know that the
+base branch was wrong, you (and only you, the submitter) can change it. {{<
+/note >}}
### Languages per PR
-Limit pull requests to one language per PR. If you need to make an identical change to the same code sample in multiple languages, open a separate PR for each language.
+Limit pull requests to one language per PR. If you need to make an identical
+change to the same code sample in multiple languages, open a separate PR for
+each language.
## Tools for contributors
-The [doc contributors tools](https://github.com/kubernetes/website/tree/main/content/en/docs/doc-contributor-tools) directory in the `kubernetes/website` repository contains tools to help your contribution journey go more smoothly.
-
+The [doc contributors tools](https://github.com/kubernetes/website/tree/main/content/en/docs/doc-contributor-tools)
+directory in the `kubernetes/website` repository contains tools to help your
+contribution journey go more smoothly.
diff --git a/content/en/docs/contribute/new-content/open-a-pr.md b/content/en/docs/contribute/new-content/open-a-pr.md
index 973a29167d..548dbac5d0 100644
--- a/content/en/docs/contribute/new-content/open-a-pr.md
+++ b/content/en/docs/contribute/new-content/open-a-pr.md
@@ -28,7 +28,40 @@ If your changes are large, read [Work from a local fork](#fork-the-repo) to lear
## Changes using GitHub
If you're less experienced with git workflows, here's an easier method of
-opening a pull request.
+opening a pull request. The figure below outlines the steps and the details follow.
+
+
+
+
+{{< mermaid >}}
+flowchart LR
+A([fa:fa-user New
Contributor]) --- id1[(K8s/Website
GitHub)]
+subgraph tasks[Changes using GitHub]
+direction TB
+ 0[ ] -.-
+ 1[1. Edit this page] --> 2[2. Use GitHub markdown
editor to make changes]
+ 2 --> 3[3. fill in Propose file change]
+
+end
+subgraph tasks2[ ]
+direction TB
+4[4. select Propose file change] --> 5[5. select Create pull request] --> 6[6. fill in Open a pull request]
+6 --> 7[7. select Create pull request]
+end
+
+id1 --> tasks --> tasks2
+
+classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
+classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
+classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff;
+classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
+class A,1,2,3,4,5,6,7 grey
+class 0 spacewhite
+class tasks,tasks2 white
+class id1 k8s
+{{ mermaid >}}
+
+***Figure - Steps for opening a PR using GitHub***
1. On the page where you see the issue, select the pencil icon at the top right.
You can also scroll to the bottom of the page and select **Edit this page**.
@@ -89,6 +122,37 @@ work from a local fork.
Make sure you have [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) installed on your computer. You can also use a git UI application.
+The figure below shows the steps to follow when you work from a local fork. The details for each step follow.
+
+
+
+
+{{< mermaid >}}
+flowchart LR
+1[Fork the K8s/website
repository] --> 2[Create local clone
and set upstream]
+subgraph changes[Your changes]
+direction TB
+S[ ] -.-
+3[Create a branch
example: my_new_branch] --> 3a[Make changes using
text editor] --> 4["Preview your changes
locally using Hugo
(localhost:1313)
or build container image"]
+end
+subgraph changes2[Commit / Push]
+direction TB
+T[ ] -.-
+5[Commit your changes] --> 6[Push commit to
origin/my_new_branch]
+end
+
+2 --> changes --> changes2
+
+classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
+classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
+classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff;
+classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
+class 1,2,3,3a,4,5,6 grey
+class S,T spacewhite
+class changes,changes2 white
+{{ mermaid >}}
+***Figure - Working from a local fork to make your changes***
+
### Fork the kubernetes/website repository
1. Navigate to the [`kubernetes/website`](https://github.com/kubernetes/website/) repository.
@@ -289,6 +353,34 @@ Alternately, install and use the `hugo` command on your computer:
### Open a pull request from your fork to kubernetes/website {#open-a-pr}
+The figure below shows the steps to open a PR from your fork to the K8s/website. The details follow.
+
+
+
+{{< mermaid >}}
+flowchart LR
+subgraph first[ ]
+direction TB
+1[1. Go to K8s/website repository] --> 2[2. Select New Pull Request]
+2 --> 3[3. Select compare across forks]
+3 --> 4[4. Select your fork from
head repository drop-down menu]
+end
+subgraph second [ ]
+direction TB
+5[5. Select your branch from
the compare drop-down menu] --> 6[6. Select Create Pull Request]
+6 --> 7[7. Add a description
to your PR]
+7 --> 8[8. Select Create pull request]
+end
+
+first --> second
+
+classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
+classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
+class 1,2,3,4,5,6,7,8 grey
+class first,second white
+{{ mermaid >}}
+***Figure - Steps to open a PR from your fork to the K8s/website***
+
1. In a web browser, go to the [`kubernetes/website`](https://github.com/kubernetes/website/) repository.
2. Select **New Pull Request**.
3. Select **compare across forks**.
@@ -303,7 +395,7 @@ Alternately, install and use the `hugo` command on your computer:
8. Select the **Create pull request** button.
- Congratulations! Your pull request is available in [Pull requests](https://github.com/kubernetes/website/pulls).
+Congratulations! Your pull request is available in [Pull requests](https://github.com/kubernetes/website/pulls).
After opening a PR, GitHub runs automated tests and tries to deploy a preview using [Netlify](https://www.netlify.com/).
@@ -414,7 +506,6 @@ If another contributor commits changes to the same file in another PR, it can cr
The pull request no longer shows any conflicts.
-
### Squashing commits
{{< note >}}
@@ -500,11 +591,8 @@ Most repositories use issue and PR templates. Have a look through some open
issues and PRs to get a feel for that team's processes. Make sure to fill out
the templates with as much detail as possible when you file issues or PRs.
-
-
## {{% heading "whatsnext" %}}
- Read [Reviewing](/docs/contribute/review/reviewing-prs) to learn more about the review process.
-
diff --git a/content/en/docs/contribute/review/reviewing-prs.md b/content/en/docs/contribute/review/reviewing-prs.md
index ff6ef9d709..9240d98f3b 100644
--- a/content/en/docs/contribute/review/reviewing-prs.md
+++ b/content/en/docs/contribute/review/reviewing-prs.md
@@ -36,7 +36,38 @@ Before you start a review:
## Review process
-In general, review pull requests for content and style in English.
+In general, review pull requests for content and style in English. The figure below outlines the steps for the review process. The details for each step follow.
+
+
+
+
+{{< mermaid >}}
+flowchart LR
+ subgraph fourth[Start review]
+ direction TB
+ S[ ] -.-
+ M[add comments] --> N[review changes]
+ N --> O[new contributors should
choose Comment]
+ end
+ subgraph third[Select PR]
+ direction TB
+ T[ ] -.-
+ J[read description
and comments]--> K[preview changes in
Netlify preview build]
+ end
+
+ A[Review open PR list]--> B[Filter open PRs
by label]
+ B --> third --> fourth
+
+
+classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
+classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
+classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
+class A,B,J,K,M,N,O grey
+class S,T spacewhite
+class third,fourth white
+{{ mermaid >}}
+
+***Figure - Review process steps***
1. Go to
[https://github.com/kubernetes/website/pulls](https://github.com/kubernetes/website/pulls).