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 +{{}} +***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 +{{}} +***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 +{{}} + +***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 +{{}} + +***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 +{{}} +***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 +{{}} +***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 +{{}} + +***Figure - Review process steps*** 1. Go to [https://github.com/kubernetes/website/pulls](https://github.com/kubernetes/website/pulls).