whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Reorganize docs contrib guide (#9510)

Browse Source 
* Reorganize docs contrib guide

* Address first round of feedback from Brad, Jared

* Standardize on 'SIG Docs'

* Address more feedback

* Rewrites to participating.md

* Tweak navigation titles

* Document PR Wrangler

* Document SIG Docs chairperson

* Fix codeblock that shows how to use <codenew>

It was being interpreted as a Hugo shortcode.
This commit is contained in:
Misty Linville
2018-08-06 16:15:57 -07:00
committed by k8s-ci-robot
parent 4920a51665
commit 5ae0d0dd8d
38 changed files with 1891 additions and 860 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/docs/contribute/_index.md
+73
View File
@@ -0,0 +1,73 @@
---
content_template: templates/concept
title: Contribute to Kubernetes docs
linktitle: Contribute
main_menu: true
weight: 80
---
{{% capture overview %}}
If you would like to help contribute to the Kubernetes documentation or website,
we're happy to have your help! Anyone can contribute, whether you're new to the
project or you've been around a long time, and whether you self-identify as a
developer, an end user, or someone who just can't stand seeing typos.
Looking for the [style guide](/docs/contribute/style/style-guide/)?
{{% /capture %}}
{{% capture body %}}
## Types of contributor
- A _member_ of the Kubernetes organization has [signed the CLA](/contribute/start#sign-the-cla)
and contributed some time and effort to the project. See
[Community membership](https://github.com/kubernetes/community/blob/master/community-membership.md)
for specific criteria for membership.
- A SIG Docs _reviewer_ is a member of the Kubernetes organization who has
expressed interest in reviewing documentation pull requests and who has been
added to the appropriate Github group and `OWNERS` files in the Github
repository, by a SIG Docs Approver.
- A SIG Docs _approver_ is a member in good standing who has shown a continued
commitment to the project and is granted the ability to merge pull requests
and thus to publish content on behalf of the Kubernetes organization.
Approvers can also represent SIG Docs in the larger Kubernetes community.
Some of the duties of a SIG Docs approver, such as coordinating a release,
require a significant time commitment.
## Ways to contribute
This list is divided into things anyone can do, things Kubernetes organization
members can do, and things that require a higher level of access and familiarity
with SIG Docs processes. Contributing consistently over time can help you
understand some of the tooling and organizational decisions that have already
been made.
This is not an exhaustive list of ways you can contribute to the Kubernetes
documentation, but it should help you get started.
- [Anyone](/docs/contribute/start/)
- File actionable bugs
- [Member](/docs/contribute/start/)
- Improve existing docs
- Bring up ideas for improvement on Slack or SIG docs mailing list
- Improve docs accessibility
- Provide non-binding feedback on PRs
- Write a blog post or case study
- [Reviewer](/docs/contribute/intermediate/)
- Document new features
- Triage and categorize issues
- Review PRs
- Create diagrams, graphics assets, and embeddable screencasts / videos
- Localization
- Contribute to other repos as a docs representative
- Edit user-facing strings in code
- Improve code comments, Godoc
- [Approver](/docs/contribute/advanced/)
- Publish contributor content by approving and merging PRs
- Participate in a Kubernetes release team as a docs representative
- Propose improvements to the style guide
- Propose improvements to docs tests
- Propose improvements to the Kubernetes website or other tooling
{{% /capture %}}
content/en/docs/contribute/advanced.md
+87
View File
@@ -0,0 +1,87 @@
---
title: Advanced contributing
slug: advanced
content_template: templates/concept
weight: 30
---
{{% capture overview %}}
This page assumes that you've read and mastered the
[Start contributing](/docs/contribute/start/) and
[Intermediate contributing](/docs/contribute/intermediate/) topics and are ready
to learn about more ways to contribute. You need to use the Git command line
client and other tools for some of these tasks.
{{% /capture %}}
{{% capture body %}}
## Be the PR Wrangler for a week
SIG Docs approvers are added to the
[PR Wrangler rotation scheduler](https://github.com/kubernetes/website/wiki/PR-Wranglers)
for weekly rotations. The PR wrangler's duties include:
- Review incoming pull requests daily.
- Help new contributors sign the CLA, and close any PR where the CLA hasn't
been signed for two weeks. PR authors can reopen the PR after signing the
CLA, so this is a low-risk way to make sure nothing gets merged without a
signed CLA.
- Provide feedback on proposed changes, including helping facilitate technical
review from members of other SIGs.
- Merge PRs when they are ready, or close PRs that shouldn't be accepted.
- Triage and tag incoming issues daily. See
[Intermediate contributing](/docs/contribute/intermediate/) for guidelines
about how SIG Docs uses metadata.
## Propose improvements
After you've been contributing to the Kubernetes documentation for a while, you
may have ideas for improvement to the style guide, the toolchain used to build
the documentation, the website style, the processes for reviewing and merging
pull requests, or other aspects of the documentation. For maximum transparency,
these types of proposals need to be discussed in a SIG Docs meeting or on the
[kubernetes-sig-docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs).
In addition, it can really help to have some context about the way things
currently work and why past decisions have been made before proposing sweeping
changes. The quickest way to get answers to questions about how the documentation
currently works is to ask in the `#sig-docs` Slack channel on
[kubernetes.slack.com](https://kubernetes.slack.com)
After discussion has taken place and the sig is in agreement about the desired
outcome, you can work on the proposed changes in the way that is the most
appropriate. For instance, an update to the style guide or the website's
functionality might involve opening a pull request, while a change related to
documentation testing might involve working with sig-testing.
## 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
release include an overall release lead, as well as representatives from sig-pm,
sig-testing, and others. To find out more about Kubernetes release processes,
refer to
[https://github.com/kubernetes/sig-release](https://github.com/kubernetes/sig-release).
The SIG Docs representative for a given release coordinates the following tasks:
- Monitor the feature-tracking spreadsheet for new or changed features with an
impact on documentation. If documentation for a given feature won't be ready
for the release, the feature may not be allowed to go into the release.
- Attend sig-release meetings regularly and give updates on the status of the
docs for the release.
- Review and copyedit feature documentation drafted by the sig responsible for
implementing the feature.
- Merge release-related pull requests and maintain the Git feature branch for
the release.
- Mentor other SIG Docs contributors who want to learn how to do this role in
the future. This is known as "shadowing".
- Publish the documentation changes related to the release when the release
artifacts are published.
Coordinating a release is typically a 3-4 month commitment, and the duty is
rotated among SIG Docs approvers.
{{% /capture %}}
content/en/docs/contribute/generate-ref-docs/_index.md
+9
View File
@@ -0,0 +1,9 @@
---
title: Reference docs overview
main_menu: true
weight: 80
---
Much of the Kubernetes reference documentation is generated from Kubernetes
source code, using scripts. The topics in this section document how to generate
this type of content.
content/en/docs/contribute/generate-ref-docs/federation-api.md
+92
View File
@@ -0,0 +1,92 @@
---
title: Generating Reference Documentation for Kubernetes Federation API
content_template: templates/task
---
{{% capture overview %}}
This page shows how to automatically generate reference pages for the
Kubernetes Federation API.
{{% /capture %}}
{{% capture prerequisites %}}
* You need to have
[Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
installed.
* You need to have
[Golang](https://golang.org/doc/install) version 1.9.1 or later installed,
and your `$GOPATH` environment variable must be set.
* You need to have
[Docker](https://docs.docker.com/engine/installation/) installed.
* You need to know how to create a pull request to a GitHub repository.
Typically, this involves creating a fork of the repository. For more
information, see
[Creating a Documentation Pull Request](/docs/home/contribute/create-pull-request/).
{{% /capture %}}
{{% capture steps %}}
## Running the update-federation-api-docs.sh script
If you don't already have the Kubernetes federation source code, get it now:
```shell
mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/federation
```
Determine the base directory of your local
[kubernetes/federation](https://github.com/kubernetes/federation) repository.
For example, if you followed the preceding step to get the federation source
code, you base directory is `$GOPATH/src/github.com/kubernetes/federation.`
The remaining steps refer to your base directory as `<fed-base>`.
Run the doc generation script:
```shell
cd <fed-base>
hack/update-federation-api-reference-docs.sh
```
The script runs the
[k8s.gcr.io/gen-swagger-docs](https://console.cloud.google.com/gcr/images/google-containers/GLOBAL/gen-swagger-docs?gcrImageListquery=%255B%255D&gcrImageListpage=%257B%2522t%2522%253A%2522%2522%252C%2522i%2522%253A0%257D&gcrImageListsize=50&gcrImageListsort=%255B%257B%2522p%2522%253A%2522uploaded%2522%252C%2522s%2522%253Afalse%257D%255D)
image to generate this set of reference docs:
* /docs/api-reference/extensions/v1beta1/operations.html
* /docs/api-reference/extensions/v1beta1/definitions.html
* /docs/api-reference/v1/operations.html
* /docs/api-reference/v1/definitions.html
The generated files do not get published automatically. They have to be manually copied to the
[kubernetes/website](https://github.com/kubernetes/website/tree/master/content/en/docs/reference/generated)
repository.
These files are published at
[kubernetes.io/docs/reference](/docs/reference/):
* [Federation API v1 Operations](https://kubernetes.io/docs/reference/federation/v1/operations/)
* [Federation API v1 Definitions](https://kubernetes.io/docs/reference/federation/v1/definitions/)
* [Federation API extensions/v1beta1 Operations](https://kubernetes.io/docs/reference/federation/extensions/v1beta1/operations/)
* [Federation API extensions/v1beta1 Definitions](https://kubernetes.io/docs/reference/federation/extensions/v1beta1/definitions/)
{{% /capture %}}
{{% capture whatsnext %}}
* [Generating Reference Documentation for the Kubernetes API](/docs/home/contribute/generated-reference/kubernetes-api/)
* [Generating Reference Documentation for kubectl Commands](/docs/home/contribute/generated-reference/kubectl/)
* [Generating Reference Pages for Kubernetes Components and Tools](/docs/home/contribute/generated-reference/kubernetes-components/)
{{% /capture %}}
content/en/docs/contribute/generate-ref-docs/kubectl.md
+265
View File
@@ -0,0 +1,265 @@
---
title: Generating Reference Documentation for kubectl Commands
content_template: templates/task
---
{{% capture overview %}}
This page shows how to automatically generate reference pages for the
commands provided by the `kubectl` tool.
{{< note >}}
**Note:**
This topic shows how to generate reference documentation for
[kubectl commands](/docs/reference/generated/kubectl/kubectl-commands)
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/)
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/).
{{< /note >}}
{{% /capture %}}
{{% capture prerequisites %}}
* You need to have
[Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
installed.
* You need to have
[Golang](https://golang.org/doc/install) version 1.9.1 or later installed,
and your `$GOPATH` environment variable must be set.
* You need to have
[Docker](https://docs.docker.com/engine/installation/) installed.
* You need to know how to create a pull request to a GitHub repository.
Typically, this involves creating a fork of the repository. For more
information, see
[Creating a Documentation Pull Request](/docs/home/contribute/create-pull-request/) and
[GitHub Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962).
{{% /capture %}}
{{% capture steps %}}
## Getting three repositories
If you don't already have the kubernetes/kubernetes repository, get it now:
```shell
mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/kubernetes
```
Determine the base directory of your clone of the
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository.
For example, if you followed the preceding step to get the repository, your
base directory is `$GOPATH/src/github.com/kubernetes/kubernetes.`
The remaining steps refer to your base directory as `<k8s-base>`.
If you don't already have the kubernetes/website repository, get it now:
```shell
mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/website
```
Determine the base directory of your clone of the
[kubernetes/website](https://github.com/kubernetes/website) repository.
For example, if you followed the preceding step to get the repository, your
base directory is `$GOPATH/src/github.com/kubernetes/website.`
The remaining steps refer to your base directory as `<web-base>`.
If you don't already have the kubernetes-incubator/reference-docs repository, get it now:
```shell
mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes-incubator/reference-docs
```
Determine the base directory of your clone of the
[kubernetes-incubator/reference-docs](https://github.com/kubernetes-incubator/reference-docs) repository.
For example, if you followed the preceding step to get the repository, your
base directory is `$GOPATH/src/github.com/kubernetes-incubator/reference-docs.`
The remaining steps refer to your base directory as `<rdocs-base>`.
In your local kubernetes/kubernetes repository, check out the branch of interest,
and make sure it is up to date. For example, if you want to generate docs for
Kubernetes 1.9, you could use these commands:
```shell
cd <k8s-base>
git checkout release-1.9
git pull https://github.com/kubernetes/kubernetes release-1.9
```
## Editing the kubectl source code
The reference documentation for the kubectl commands is automatically generated from
kubectl source code. If you want to change the reference documentation, the first step
is to change one or more comments in the kubectl source code. Make the change in your
local kubernetes/kubernetes repository, and then submit a pull request to the master branch of
[github.com/kubernetes/kubernetes](https://github.com/kubernetes/kubernetes).
[PR 56673](https://github.com/kubernetes/kubernetes/pull/56673/files)
is an example of a pull request that fixes a typo in the kubectl source code.
Monitor your pull request, and respond to reviewer comments. Continue to monitor your
pull request until it is merged into the master branch of the kubernetes/kubernetes repository.
## Cherry picking your change into a release branch
Your change is now in the master branch, which is used for development of the next
Kubernetes release. If you want your change to appear in the docs for a Kubernetes
version that has already been released, you need to propose that your change be
cherry picked into the release branch.
For example, suppose the master branch is being used to develop Kubernetes 1.10,
and you want to backport your change to the release-1.9 branch. For instructions
on how to do this, see
[Propose a Cherry Pick](https://github.com/kubernetes/community/blob/master/contributors/devel/cherry-picks.md).
Monitor your cherry-pick pull request until it is merged into the release branch.
{{< note >}}
**Note:**
Proposing a cherry pick requires that you have permission to set a label and a
milestone in your pull request. If you don’t have those permissions, you will
need to work with someone who can set the label and milestone for you.
{{< /note >}}
## Editing Makefile
Go to `<rdocs-base>`, and open `Makefile` for editing:
Set `K8SROOT` to the base directory of your local kubernetes/kubernetes
repository. Set `WEBROOT` to the base directory of your local kubernetes/website repository.
Set `MINOR_VERSION` to the minor version of the docs you want to build. For example,
if you want to build docs for Kubernetes 1.9, set `MINOR_VERSION` to 9. Save and close `Makefile`.
## Building the brodocs image
The doc generation code requires the `pwittrock/brodocs` Docker image.
This command creates the `pwittrock/brodocs` Docker image. It also tries to push the image to
DockerHub, but it's OK if that step fails. As long as you have the image locally, the code generation
can succeed.
```shell
make brodocs
```
Verify that you have the brodocs image:
```shell
docker images
```
The output shows `pwittrock/brodocs` as one of the available images:
```shell
REPOSITORY TAG IMAGE ID CREATED SIZE
pwittrock/brodocs latest 999d34a50d56 5 weeks ago 714MB
```
## Creating a version directory
In the `gen-kubectldocs/generators` directory, if you do not already
have a directory named `v1_MINOR_VERSION`, create one now by copying the directory
for the previous version. For example, suppose you want to generate docs for
Kubernetes 1.9, but you don't already have a `v1_9` directory. Then you could
create and populate a `v1_9` directory by running these commands:
```shell
mkdir gen-kubectldocs/generators/v1_9
cp -r gen-kubectldocs/generators/v1_8/* gen-kubectldocs/generators/v1_9
```
## Checking out a branch in kubernetes/kubernetes
In you local kubernetes/kubernetes repository, checkout the branch that has
the version of Kubernetes that you want to document. For example, if you want
to generate docs for Kubernetes 1.9, checkout the release-1.9 branch. Make sure
you local branch is up to date.
## Running the doc generation code
In you local kubernetes-incubator/reference-docs repository, build and run the
doc generation code. You might need to run the command as root:
```shell
cd <rdocs-base>
make cli
```
## Locate the generated files
These two files are the primary output of a successful build. Verify that they exist:
* `<rdocs-base>/gen-kubectldocs/generators/build/index.html`
* `<rdocs-base>/gen-kubectldocs/generators/build/navData.js`
## Copying files to the kubernetes/website repository
Copy the generated files from your local kubernetes-incubator/reference-docs
repository to your local kubernetes/website repository.
```shell
cd <rdocs-base>
make copycli
```
## Adding and committing changes in kubernetes/website
List the files that were generated and copied to the `kubernetes/website`
repository:
```
cd <web-base>
git status
```
The output shows the new and modified files. For example, the output
might look like this:
```shell
modified: docs/reference/generated/kubectl/kubectl-commands.html
modified: docs/reference/generated/kubectl/navData.js
```
Run `git add` and `git commit` to commit the files.
## Creating a pull request
Create a pull request to the `kubernetes/website` repository. Monitor your
pull request, and respond to review comments as needed. Continue to monitor
your pull request until it is merged.
A few minutes after your pull request is merged, your updated reference
topics will be visible in the
[published documentation](/docs/home).
{{% /capture %}}
{{% capture whatsnext %}}
* [Generating Reference Documentation for Kubernetes Components and Tools](/docs/home/contribute/generated-reference/kubernetes-components/)
* [Generating Reference Documentation for the Kubernetes API](/docs/home/contribute/generated-reference/kubernetes-api/)
* [Generating Reference Documentation for the Kubernetes Federation API](/docs/home/contribute/generated-reference/federation-api/)
{{% /capture %}}
content/en/docs/contribute/generate-ref-docs/kubernetes-api.md
+379
View File
@@ -0,0 +1,379 @@
---
title: Generating Reference Documentation for the Kubernetes API
content_template: templates/task
---
{{% capture overview %}}
This page shows how to update the automatically generated reference docs for the
Kubernetes API.
{{% /capture %}}
{{% capture prerequisites %}}
You need to have these tools installed:
* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
* [Golang](https://golang.org/doc/install) version 1.9.1 or later
* [Docker](https://docs.docker.com/engine/installation/)
* [etcd](https://github.com/coreos/etcd/)
Your $GOPATH environment variable must be set, and the location of `etcd`
must be in your $PATH environment variable.
You need to know how to create a pull request to a GitHub repository.
Typically, this involves creating a fork of the repository. For more
information, see
[Creating a Documentation Pull Request](/docs/home/contribute/create-pull-request/) and
[GitHub Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962).
{{% /capture %}}
{{% capture steps %}}
## The big picture
Updating the Kubernetes API reference documentation is a two-stage process:
1. Generate an OpenAPI spec from the Kubernetes source code. The tools for
this stage are at [kubernetes/kubernetes/hack](https://github.com/kubernetes/kubernetes/tree/master/hack).
1. Generate an HTML file from the OpenAPI spec. The tools for this stage are at
[kubernetes-incubator/reference-docs](https://github.com/kubernetes-incubator/reference-docs).
## Getting three repositories
If you don't already have the kubernetes/kubernetes repository, get it now:
```shell
mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/kubernetes
```
Determine the base directory of your clone of the
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository.
For example, if you followed the preceding step to get the repository, your
base directory is `$GOPATH/src/github.com/kubernetes/kubernetes.`
The remaining steps refer to your base directory as `<k8s-base>`.
If you don't already have the kubernetes/website repository, get it now:
```shell
mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/website
```
Determine the base directory of your clone of the
[kubernetes/website](https://github.com/kubernetes/website) repository.
For example, if you followed the preceding step to get the repository, your
base directory is `$GOPATH/src/github.com/kubernetes/website.`
The remaining steps refer to your base directory as `<web-base>`.
If you don't already have the kubernetes-incubator/reference-docs repository, get it now:
```shell
mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes-incubator/reference-docs
```
Determine the base directory of your clone of the
[kubernetes-incubator/reference-docs](https://github.com/kubernetes-incubator/reference-docs) repository.
For example, if you followed the preceding step to get the repository, your
base directory is `$GOPATH/src/github.com/kubernetes-incubator/reference-docs.`
The remaining steps refer to your base directory as `<rdocs-base>`.
## Editing the Kubernetes source code
The Kubernetes API reference documentation is automatically generated from
an OpenAPI spec, which is generated from the Kubernetes source code. If you
want to change the reference documentation, the first step is to change one
or more comments in the Kubernetes source code.
### Making changes to comments in the source code
{{< note >}}
**Note**: The following steps are an example, not a general procedure. Details
will be different in your situation.
{{< /note >}}
Here's an example of editing a comment in the Kubernetes source code.
In your local kubernetes/kubernetes repository, check out the master branch,
and make sure it is up to date:
```shell
cd <k8s-base>
git checkout master
git pull https://github.com/kubernetes/kubernetes master
```
Suppose this source file in the master branch has the typo "atmost":
[kubernetes/kubernetes/staging/src/k8s.io/api/apps/v1/types.go](https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/api/apps/v1/types.go)
In your local environment, open `types.go`, and change "atmost" to "at most".
Verify that you have changed the file:
```shell
git status
```
The output shows that you are on the master branch, and that the `types.go`
source file has been modified:
```shell
On branch master
...
modified: staging/src/k8s.io/api/apps/v1/types.go
```
### Committing your edited file
Run `git add` and `git commit` to commit the changes you have made so far. In the next step,
you will do a second commit. It is important to keep your changes separated into two commits.
### Generating the OpenAPI spec and related files
Go to `<k8s-base>` and run these scripts:
```shell
hack/update-generated-swagger-docs.sh
hack/update-swagger-spec.sh
hack/update-openapi-spec.sh
hack/update-generated-protobuf.sh
hack/update-api-reference-docs.sh
```
Run `git status` to see what was generated.
```shell
On branch master
...
modified: api/openapi-spec/swagger.json
modified: api/swagger-spec/apps_v1.json
modified: docs/api-reference/apps/v1/definitions.html
modified: staging/src/k8s.io/api/apps/v1/generated.proto
modified: staging/src/k8s.io/api/apps/v1/types.go
modified: staging/src/k8s.io/api/apps/v1/types_swagger_doc_generated.go
```
View the contents of `api/openapi-spec/swagger.json` to make sure the typo is fixed.
For example, you could run `git diff -a api/openapi-spec/swagger.json`.
This is important, because `swagger.json` will be the input to the second stage of
the doc generation process.
Run `git add` and `git commit` to commit your changes. Now you have two commits:
one that has the edited `types.go` file, and one that has the generated OpenAPI spec
and related files. Keep these two commits separate. That is, do not squash your commits.
Submit your changes as a
[pull request](https://help.github.com/articles/creating-a-pull-request/) to the
master branch of the
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository.
Monitor your pull request, and respond to reviewer comments as needed. Continue
to monitor your pull request until it has been merged.
[PR 57758](https://github.com/kubernetes/kubernetes/pull/57758)
is an example of a pull request that fixes a typo in the Kubernetes source code.
{{< note >}}
**Note**: It can be tricky to determine the correct source file to be changed. In the
preceding example, the authoritative source file is under the `staging` directory
in the `kubernetes/kubernetes` repository. But in your situation,the `staging` directory
might not be the place to find the authoritative source. For guidance, check the
`README` files in
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes/tree/master/staging)
repository and in related repositories like
[kubernetes/apiserver](https://github.com/kubernetes/apiserver/blob/master/README.md).
{{< /note >}}
### Cherry picking your commit into a release branch
In the preceding section, you edited a file in the master branch and then ran scripts
to generate an OpenAPI spec and related files. Then you submitted your changes in a pull request
to the master branch of the kubernetes/kubernetes repository. Now suppose you want to backport
your change into a release branch. For example, suppose the master branch is being used to develop
Kubernetes version 1.10, and you want to backport your change into the release-1.9 branch.
Recall that your pull request has two commits: one for editing `types.go`
and one for the files generated by scripts. The next step is to propose a cherry pick of your first
commit into the release-1.9 branch. The idea is to cherry pick the commit that edited `types.go`, but not
the commit that has the results of running the scripts. For instructions, see
[Propose a Cherry Pick](https://github.com/kubernetes/community/blob/master/contributors/devel/cherry-picks.md).
**Note:** Proposing a cherry pick requires that you have permission to set a label and a milestone in your
pull request. If you don't have those permissions, you will need to work with someone who can set the label
and milestone for you.
When you have a pull request in place for cherry picking your one commit into the release-1.9 branch,
the next step is to run these scripts in the release-1.9 branch of your local environment.
```shell
hack/update-generated-swagger-docs.sh
hack/update-swagger-spec.sh
hack/update-openapi-spec.sh
hack/update-generated-protobuf.sh
hack/update-api-reference-docs.sh
```
Now add a commit to your cherry-pick pull request that has the recently generated OpenAPI spec
and related files. Monitor your pull request until it gets merged into the release-1.9 branch.
At this point, both the master branch and the release-1.9 branch have your updated `types.go`
file and a set of generated files that reflect the change you made to `types.go`. Note that the
generated OpenAPI spec and other generated files in the release-1.9 branch are not necessarily
the same as the generated files in the master branch. The generated files in the release-1.9 branch
contain API elements only from Kubernetes 1.9. The generated files in the master branch might contain
API elements that are not in 1.9, but are under development for 1.10.
## Generating the published reference docs
The preceding section showed how to edit a source file and then generate
several files, including `api/openapi-spec/swagger.json` in the
`kubernetes/kubernetes` repository.
This section shows how to generate the
[published Kubernetes API reference documentation](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/),
which is generated by the tools at
[kubernetes-incubator/reference-docs](https://github.com/kubernetes-incubator/reference-docs).
Those tools take the `api/openapi-spec/swagger.json` file as input.
### Editing Makefile in kubernetes-incubator/reference-docs
Go to `<rdocs-base>`, and open `Makefile` for editing:
Set `K8SROOT` to the base directory of your local kubernetes/kubernetes
repository. Set `WEBROOT` to the base directory of your local kubernetes/website repository.
Set `MINOR_VERSION` to the minor version of the docs you want to build. For example,
if you want to build docs for Kubernetes 1.9, set `MINOR_VERSION` to 9. Save and close `Makefile`.
### Copying the OpenAPI spec
The doc generation code needs a local copy of the OpenAPI spec for the Kubernetes API.
Go to `<k8s-base>` and check out the branch that has the OpenAPI spec you want to use.
For example, if you want to generate docs for Kubernetes 1.9, checkout the release-1.9
branch.
Go back to `<rdocs-base>`. Enter the following command to copy the OpenAPI spec from the
`kubernetes/kubernetes` repository to a local directory:
```shell
make updateapispec
```
The output shows that the file was copied:
```shell
cp ~/src/github.com/kubernetes/kubernetes/api/openapi-spec/swagger.json gen-apidocs/generators/openapi-spec/swagger.json
```
### Building the brodocs image
The doc generation code requires the
[pwittrock/brodocs](https://github.com/pwittrock/brodocs) Docker image.
This command creates the `pwittrock/brodocs` Docker image. It also tries to push the image to
DockerHub, but it's OK if that step fails. As long as you have the image locally, the code generation
can succeed.
```shell
make brodocs
```
Verify that you have the brodocs image:
```shell
docker images
```
The output shows `pwittrock/brodocs` as one of the available images:
```shell
REPOSITORY TAG IMAGE ID CREATED SIZE
pwittrock/brodocs latest 999d34a50d56 5 weeks ago 714MB
```
### Running the doc generation code
Build and run the doc generation code. You might need to run the command as root:
```shell
cd <rdocs-base>
make api
```
### Locate the generated files
These two files are the output of a successful build. Verify that they exist:
* `<rdocs-base>/gen-apidocs/generators/build/index.html`
* `<rdocs-base>/gen-apidocs/generators/build/navData.js`
## Copying the generated docs to the kubernetes/website repository
The preceding sections showed how to edit a Kubernetes source file,
generate an OpenAPI spec, and then generate reference documentation for publication.
This section show how to copy the generated docs to the
[kubernetes/website](https://github.com/kubernetes/website) repository. The files
in the `kubernetes/website` repository are published in the
[kubernetes.io](https://kubernetes.io) website. In particular, the generated
`index.html` file is published [here](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).
Enter the following command to copy the generated files to
your local kubernetes/website repository:
```shell
make copyapi
```
Go to the base of your local kubernetes/kubernetes repository, and
see which files have been modified:
```shell
cd <web-base>
git status
```
The output shows the modified files:
```shell
On branch master
...
modified: docs/reference/generated/kubernetes-api/v1.9/index.html
```
In this example, only one file has been modified. Recall that you generated both
`index.html` and `navData.js`. But apparently the generated `navata.js` is not different
from the `navData.js` that was already in the kubernetes/website` repository.
In `<web-base>` run `git add` and `git commit` to commit the change.
Submit your changes as a
[pull request](/docs/home/contribute/create-pull-request/) 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.
A few minutes after your pull request is merged, your changes will be visible
in the [published reference documentation](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).
{{% /capture %}}
{{% capture whatsnext %}}
* [Generating Reference Docs for Kubernetes Components and Tools](/docs/home/contribute/generated-reference/kubernetes-components/)
* [Generating Reference Documentation for kubectl Commands](/docs/home/contribute/generated-reference/kubectl/)
* [Generating Reference Documentation for the Kubernetes Federation API](/docs/home/contribute/generated-reference/federation-api/)
{{% /capture %}}
content/en/docs/contribute/generate-ref-docs/kubernetes-components.md
+306
View File
@@ -0,0 +1,306 @@
---
title: Generating Reference Pages for Kubernetes Components and Tools
content_template: templates/task
---
{{% capture overview %}}
This page shows how to use the `update-imported-docs` tool to generate
reference documentation for tools and components in the
[Kubernetes](https://github.com/kubernetes/kubernetes) and
[Federation](https://github.com/kubernetes/federation) repositories.
{{% /capture %}}
{{% capture prerequisites %}}
* You need a machine that is running Linux or macOS.
* You need to have this software installed:
* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
* [Golang](https://golang.org/doc/install) version 1.9 or later
* [make](https://www.gnu.org/software/make/)
* [gcc compiler/linker](https://gcc.gnu.org/)
* Your `$GOPATH` environment variable must be set.
* You need to know how to create a pull request to a GitHub repository.
Typically, this involves creating a fork of the repository. For more
information, see
[Creating a Documentation Pull Request](/docs/home/contribute/create-pull-request/).
{{% /capture %}}
{{% capture steps %}}
## Getting two repositories
If you don't already have the `kubernetes/website` repository, get it now:
```shell
mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/website
```
Determine the base directory of your clone of the
[kubernetes/website](https://github.com/kubernetes/website) repository.
For example, if you followed the preceding step to get the repository,
your base directory is `$GOPATH/src/github.com/kubernetes/website.`
The remaining steps refer to your base directory as `<web-base>`.
If you plan on making changes to the ref docs, and if you don't already have
the `kubernetes/kubernetes` repository, get it now:
```shell
mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/kubernetes
```
Determine the base directory of your clone of the
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository.
For example, if you followed the preceding step to get the repository,
your base directory is `$GOPATH/src/github.com/kubernetes/kubernetes.`
The remaining steps refer to your base directory as `<k8s-base>`.
{{< note >}}
**Note:**
If you only need to generate, but not change, the reference docs, you don't need to
manually get the `kubernetes/kubernetes` repository. When you run the `update-imported-docs`
tool, it automatically clones the `kubernetes/kubernetes` repository.
{{< /note >}}
## Editing the Kubernetes source code
The reference documentation for the Kubernetes components and tools is automatically
generated from the Kubernetes source code. If you want to change the reference documentation,
the first step is to change one or more comments in the Kubernetes source code. Make the
change in your local kubernetes/kubernetes repository, and then submit a pull request to
the master branch of
[github.com/kubernetes/kubernetes](https://github.com/kubernetes/kubernetes).
[PR 56942](https://github.com/kubernetes/kubernetes/pull/56942)
is an example of a pull request that makes changes to comments in the Kubernetes
source code.
Monitor your pull request, and respond to reviewer comments. Continue to monitor
your pull request until it is merged into the master branch of the
`kubernetes/kubernetes` repository.
## Cherry picking your change into a release branch
Your change is now in the master branch, which is used for development of the next
Kubernetes release. If you want your change to appear in the docs for a Kubernetes
version that has already been released, you need to propose that your change be cherry
picked into the release branch.
For example, suppose the master branch is being used to develop Kubernetes 1.10, and
you want to backport your change to the release-1.9 branch. For instructions on how
to do this, see
[Propose a Cherry Pick](https://github.com/kubernetes/community/blob/master/contributors/devel/cherry-picks.md).
Monitor your cherry-pick pull request until it is merged into the release branch.
{{< note >}}
**Note:** Proposing a cherry pick requires that you have permission to set a label
and a milestone in your pull request. If you don’t have those permissions, you will
need to work with someone who can set the label and milestone for you.
{{< /note >}}
## Overview of update-imported-docs
The `update-imported-docs` tool performs these steps:
1. Clone the `kubernetes/kubernetes` repository.
1. Run several scripts under `kubernetes/kubernetes/hack`. These scripts
generate Markdown files and place the files under `kubernetes/kubernetes/docs`.
1. Copy the generated Markdown files to a local clone of the `kubernetes/website`
repository under `kubernetes/website/docs/reference/generated`.
1. Clone the `kubernetes/federation` repository.
1. Run several scripts under `kubernetes/federation/hack`. These scripts
generate Markdown files and place the files under `kubernetes/federation/docs`.
1. Copy the generated Markdown files to a local clone of the `kubernetes/website`
repository under `kubernetes/website/docs/reference/generated`.
After the Markdown files are in your local clone of the `kubernetes/website`
repository, you can submit them in a
[pull request](https://kubernetes.io/docs/home/contribute/create-pull-request/)
to `kubernetes/website`.
## Setting the branch
Open `<web-base>/update-imported-docs/config.yaml` for editing.
Set the value of `branch` to the Kubernetes release that you want to document.
For example, if you want to generate docs for the Kubernetes 1.9 release,
set `branch` to `release-1.9`.
```shell
repos:
- name: kubernetes
remote: https://github.com/kubernetes/kubernetes.git
branch: release-1.9
```
## Setting sources and destinations
The `update-imported-docs` tool uses `src` and `dst` fields
in `config.yaml` to know which files to copy from the `kubernetes/kubernetes`
repository and where to place those files in the `kubernetes/website`
repository.
For example, suppose you want the tool to copy the `kube-apiserver.md` file
from the `docs/admin` directory of the `kubernetes/kubernetes` repository
to the `docs/reference/generated/` directory of the `kubernetes/website`
repository. Then you would include a `src` and `dst` in your `config.yaml`
file like this:
```shell
repos:
- name: kubernetes
remote: https://github.com/kubernetes/kubernetes.git
branch: release-1.9
files:
- src: docs/admin/kube-apiserver.md
dst: docs/reference/generated/kube-apiserver.md
...
```
The configuration is similar for files in the `kubernetes/federation`
repository. Here's an example that configures the tool to copy `kubefed_init.md`
from the `docs/admin` directory of the `kubernetes/federation` repository
to the `docs/reference/generated` directory of the `kubernetes/website` repository:
```shell
- name: federation
remote: https://github.com/kubernetes/federation.git
# # Change this to a release branch when federation has release branches.
branch: master
files:
- src: docs/admin/kubefed_init.md
dst: docs/reference/generated/kubefed_init.md
...
```
Here's an example a `config.yaml` file that shows the sources and
destinations of all the Markdown files that were generated and copied
by the `update-imported-docs` tool at the beginning of the Kubernetes
1.9 release.
```shell
repos:
- name: kubernetes
remote: https://github.com/kubernetes/kubernetes.git
branch: release-1.9
files:
- src: docs/admin/cloud-controller-manager.md
dst: docs/reference/generated/cloud-controller-manager.md
- src: docs/admin/kube-apiserver.md
dst: docs/reference/generated/kube-apiserver.md
- src: docs/admin/kube-controller-manager.md
dst: docs/reference/generated/kube-controller-manager.md
- src: docs/admin/kubelet.md
dst: docs/reference/generated/kubelet.md
- src: docs/admin/kube-proxy.md
dst: docs/reference/generated/kube-proxy.md
- src: docs/admin/kube-scheduler.md
dst: docs/reference/generated/kube-scheduler.md
- src: docs/user-guide/kubectl/kubectl.md
dst: docs/reference/generated/kubectl/kubectl.md
- name: federation
remote: https://github.com/kubernetes/federation.git
# # Change this to a release branch when federation has release branches.
branch: master
files:
- src: docs/admin/federation-apiserver.md
dst: docs/reference/generated/federation-apiserver.md
- src: docs/admin/federation-controller-manager.md
dst: docs/reference/generated/federation-controller-manager.md
- src: docs/admin/kubefed_init.md
dst: docs/reference/generated/kubefed_init.md
- src: docs/admin/kubefed_join.md
dst: docs/reference/generated/kubefed_join.md
- src: docs/admin/kubefed.md
dst: docs/reference/generated/kubefed.md
- src: docs/admin/kubefed_options.md
dst: docs/reference/generated/kubefed_options.md
- src: docs/admin/kubefed_unjoin.md
dst: docs/reference/generated/kubefed_unjoin.md
- src: docs/admin/kubefed_version.md
dst: docs/reference/generated/kubefed_version.md
```
## Running the update-imported-docs tool
Now that your `config.yaml` file contains your sources and destinations,
you can run the `update-imported-docs` tool:
```shell
cd <web-base>
go get ./update-imported-docs
go run update-imported-docs/update-imported-docs.go
```
## Adding and committing changes in kubernetes/website
List the files that were generated and copied to the `kubernetes/website`
repository:
```
cd <web-base>
git status
```
The output shows the new and modified files. For example, the output
might look like this:
```shell
...
modified: docs/reference/generated/cloud-controller-manager.md
modified: docs/reference/generated/federation-apiserver.md
modified: docs/reference/generated/federation-controller-manager.md
modified: docs/reference/generated/kube-apiserver.md
modified: docs/reference/generated/kube-controller-manager.md
modified: docs/reference/generated/kube-proxy.md
modified: docs/reference/generated/kube-scheduler.md
modified: docs/reference/generated/kubectl/kubectl.md
modified: docs/reference/generated/kubefed.md
modified: docs/reference/generated/kubefed_init.md
modified: docs/reference/generated/kubefed_join.md
modified: docs/reference/generated/kubefed_options.md
modified: docs/reference/generated/kubefed_unjoin.md
modified: docs/reference/generated/kubefed_version.md
modified: docs/reference/generated/kubelet.md
```
Run `git add` and `git commit` to commit the files.
## Creating a pull request
Create a pull request to the `kubernetes/website` repository. Monitor your
pull request, and respond to review comments as needed. Continue to monitor
your pull request until it is merged.
A few minutes after your pull request is merged, your updated reference
topics will be visible in the
[published documentation](/docs/home/).
{{% /capture %}}
{{% capture whatsnext %}}
* [Generating Reference Documentation for kubectl Commands](/docs/home/contribute/generated-reference/kubectl/)
* [Generating Reference Documentation for the Kubernetes API](/docs/home/contribute/generated-reference/kubernetes-api/)
* [Generating Reference Documentation for the Kubernetes Federation API](/docs/home/contribute/generated-reference/federation-api/)
{{% /capture %}}
content/en/docs/contribute/intermediate.md
+789
View File
@@ -0,0 +1,789 @@
---
title: Intermediate contributing
slug: intermediate
content_template: templates/concept
weight: 20
---
{{% capture overview %}}
This page assumes that you've read and mastered the tasks in the
[start contributing](/docs/contribute/start/) topic and are ready to
learn about more ways to contribute.
{{< note >}}
**Note:** Some tasks require you to use the Git command line client and other
tools.
{{< /note >}}
{{% /capture %}}
{{% capture body %}}
Now that you've gotten your feet wet and helped out with the Kubernetes docs in
the ways outlined in the [start contributing](/docs/contribute/start/) topic,
you may feel ready to do more. These tasks assume that you have, or are willing
to gain, deeper knowledge of the following topic areas:
- Kubernetes concepts
- Kubernetes documentation workflows
- Where and how to find information about upcoming Kubernetes features
- Strong research skills in general
These tasks are not as sequential as the beginner tasks. There is no expectation
that one person does all of them all of the time.
## Review pull requests
In any given week, a specific docs approver volunteers to do initial triage
and review of [pull requests and issues](#triage-and-categorize-issues). This
person is the "PR Wrangler" for the week. The schedule is maintained using the
[PR Wrangler scheduler(https://github.com/kubernetes/website/wiki/PR-Wranglers).
To be added to this list, attend the weekly SIG Docs meeting and volunteer. Even
if you are not on the schedule for the current week, you can still review pull
requests (PRs) that are not already under active review.
In addition to the rotation, an automated system comments on each new PR and
suggests reviewers and approvers for the PR, based on the list of approvers and
reviewers in the affected files. The PR author is expected to follow the
guidance of the bot, and this also helps PRs to get reviewed quickly.
We want to get pull requests (PRs) merged and published as quickly as possible.
To ensure the docs are accurate and up to date, each PR needs to be reviewed by
people who understand the content, as well as people with experience writing
great documentation.
Reviewers and approvers need to provide actionable and constructive feedback to
keep contributors engaged and help them to improve. Sometimes helping a new
contributor get their PR ready to merge takes more time than just rewriting it
yourself, but the project is better in the long term when we have a diversity of
active participants.
Before you start reviewing PRs, make sure you are familiar with the
[Documentation Style Guide](/docs/contribute/style/style-guide/)
and the [code of conduct]() <!-- TODO when #9355 is merged -->
### Find a PR to review
To see all open PRs, go to the **Pull Requests** tab in the Github repository.
A PR is eligible for review when it meets all of the following criteria:
- Has the `cnf-cla:yes` tag
- Does not have WIP in the description
- Does not a have tag including the phrase `do-not-merge`
- Has no merge conflicts
- Is based against the correct branch (usually `master` unless the PR relates to
a feature that has not yet been released)
- Is not being actively reviewed by another docs person (other technical
reviewers are fine), unless that person has explicitly asked for your help. In
particular, leaving lots of new comments after other review cycles have
already been completed on a PR can be discouraging and counter-productive.
If a PR is not eligible to merge, leave a comment to let the author know about
the problem and offer to help them fix it. If they've been informed and have not
fixed the problem in several weeks or months, eventually their PR will be closed
without merging.
If you're new to reviewing, or you don't have a lot of bandwidth, look for PRs
with the `size/XS` or `size/S` tag set. The size is automatically determined by
the number of lines the PR changes.
#### Reviewers and approvers
The Kubernetes website repo operates differently than some of the Kubernetes
code repositories when it comes to the roles of reviewers and approvers. For
more information about the responsibilities of reviewers and approvers, see
[Participating](/docs/contribute/participating/). Here's an overview.
- A reviewer reviews pull request content for technical accuracy. A reviewer
indicates that a PR is technically accurate by leaving a `/lgtm` comment on
the PR.
{{< note >}}Don't add an `/lgtm` unless you are confident in the technical
accuracy of the documentation modified or introduced in the PR.{{< /note >}}
- An approver reviews pull request content for docs quality and adherence to
SIG Docs guidelines, such as the
[style guide](/docs/contribute/style/style-guide). Only people listed as
approvers in the
[`OWNERS`](https://github.com/kubernetes/website/blob/master/OWNERS) file can
approve a PR. To approve a PR, leave an `/approved` comment on the PR.
A PR is merged when it has both a `/lgtm` comment from anyone in the Kubernetes
organization and an `/approved` comment from an approver in the
`sig-docs-maintainers` group, as long as it is not on hold and the PR author
has signed the CLA.
### Review a PR
1. Read the PR description and read any attached issues or links, if
applicable. "Drive-by reviewing" is sometimes more harmful than helpful, so
make sure you have the right knowledge to provide a meaningful review.
2. If someone else is the best person to review this particular PR, let them
know by adding a comment with `/assign @<github-username>`. If you have
asked a non-docs person for technical review but still want to review the PR
from a docs point of view, keep going.
3. Go to the **Files changed** tab. Look over all the changed lines. Removed
content has a red background, and those lines also start with a `-` symbol.
Added content has a green background, and those lines also start with a `+`
symbol. Within a line, the actual modified content has a slightly darker
green background than the rest of the line.
- Especially if the PR uses tricky formatting or changes CSS, Javascript,
or other site-wide elements, you can preview the website with the PR
applied. Go to the **Conversation** tab and click the **Details** link
for the `deploy/netlify` test, near the bottom of the page. It opens in
the same browser window by default, so open it in a new window so you
don't lose your partial review. Switch back to the **Files changed** tab
to resume your review.
- Make sure the PR complies with the
[Documentation Style Guide](/docs/contribute/style/style-guide/)
and link the author to the relevant part of the style guide if not.
- If you have a question, comment, or other feedback about a given
change, hover over a line and click the blue-and-white `+` symbol that
appears. Type your comment and click **Start a review**.
- If you have more comments, leave them in the same way.
- By convention, if you see a small problem that does not have to do with
the main purpose of the PR, such as a typo or whitespace error, you can
call it out, prefixing your comment with `nit:` so that the author knows
you consider it trivial. They should still address it.
- When you're reviewed everything, or if you didn't have any comments, go
back to the top of the page and click **Review changes**. Choose either
**Comment** or **Request Changes**. Add a summary of your review, and
add appropriate
[Prow commands](https://prow.k8s.io/command-help) to separate lines in
the Review Summary field. SIG Docs follows the
[Kubernetes code review process](https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md#the-code-review-process).
All of your comments will be sent to the PR author in a single
notification.
- If you think the PR is ready to be merged, add the text `/approve` to
your summary.
- If the PR does not need additional technical review, add the
text `/lgtm` as well.
- If the PR *does* need additional technical review, add the text
`/assign` with the Github username of the person who needs to
provide technical review. Look at the `reviewers` field in the
front-matter at the top of a given Markdown file to see who can
provide technical review.
- To prevent the PR from being merged, add `/hold`. This sets the
label `do-not-merge/hold`.
- If a PR has no conflicts and has the `lgtm` and `approved` label but
no `hold` label, it is merged automatically.
- If a PR has the `lgtm` and/or `approved` labels and new changes are
detected, these labels are removed automatically.
See
[the list of all available slash commands](https://prow.k8s.io/command-help)
that can be used in PRs.
- If you previously selected **Request changes** and the PR author has
addressed your concerns, you can change your review status either in the
**Files changed** tab or at the bottom of the **Conversation** tab. Be
sure to add the `/approve` tag and assign technical reviewers if necessary,
so that the PR can be merged.
### Commit into another person's PR
Leaving PR comments is helpful, but there may be times when you need to commit
into another person's PR, rather than just leaving a review.
Resist the urge to "take over" for another person unless they explicitly ask
you to, or you want to resurrect a long-abandoned PR. While it may be faster
in the short term, it deprives the person of the chance to contribute.
The process you use depends on whether you need to edit a file that is already
in the scope of the PR or a file that the PR has not yet touched.
You can't commit into someone else's PR if either of the following things is
true:
- If the PR author pushed their branch directly to the
[https://github.com/kubernetes/website/](https://github.com/kubernetes/website/)
repository, only a reviewer with push access can commit into their PR.
Authors should be encouraged to push their branch to their fork before
opening the PR.
- If the PR author explicitly disallowed edits from approvers, you can't
commit into their PR unless they change this setting.
#### If the file is already changed by the PR
This method uses the Github UI. If you prefer, you can use the command line
even if the file you want to change is part of the PR, if you are more
comfortable working that way.
1. Click the **Files changed** tab.
2. Scroll down to the file you want to edit, and click the pencil icon for
that file.
3. Make your changes, add a commit message in the field below the editor, and
click **Commit changes**.
Your commit is now pushed to the branch the PR represents (probably on the
author's fork) and now shows up in the PR and your changes are reflected in
the **Files changed** tab. Leave a comment letting the PR author know you
changed the PR.
If the author is using the command line rather than the Github UI to work on
this PR, they need to fetch their fork's changes and rebase their local branch
on the branch in their fork, before doing additional work on the PR.
#### If the file has not yet been changed by the PR
If changes need to be made to a file that is not yet included in the PR, you
need to use the command line. You can always use this method, if you prefer it
to the Github UI.
1. Get the URL for the author's fork. You can find it near the bottom of the
**Conversation** tab. Look for the text "Add more commits by pushing to".
The first link after this phrase is to the branch, and the second link is
to the fork. Copy the second link. Note the name of the branch for later.
2. Add the fork as a remote. In your terminal, go to your clone of the
repository. Decide on a name to give the remote (such as the author's
Github username), and add the remote using the following syntax:
```bash
git remote add <name> <url-of-fork>
```
3. Fetch the remote. This doesn't change any local files, but updates your
clone's notion of the remote's objects (such as branches and tags) and
their current state.
```bash
git remote fetch <name>
```
4. Check out the remote branch. This command will fail if you already have a
local branch with the sane name.
```bash
git checkout <branch-from-PR>
```
5. Make your changes, use `git add` to add them, and commit them.
6. Push your changes to the author's remote.
```bash
git push <remote-name> <branch-name>
```
7. Go back to the Github IU and refresh the PR. Your changes appear. Leave the
PR author a comment letting them know you changed the PR.
If the author is using the command line rather than the Github UI to work on
this PR, they need to fetch their fork's changes and rebase their local branch
on the branch in their fork, before doing additional work on the PR.
## Work from a local clone
For changes that require multiple files or changes that involve creating new
files or moving files around, working from a local Git clone makes more sense
than relying on the Github UI. These instructions use the `git` command and
assume that you have it installed locally. You can adapt them to use a local
graphical Git client instead.
### Clone the repository
You only need to clone the repository once per physical system where you work
on the Kubernetes documentation.
1. In a terminal window, use `git clone` to clone the repository. You do not
need any credentials to clone the repository.
```bash
git clone https://github.com/kubernetes/website
```
The new directory `website` is created in your current directory, with
the contents of the Github repository.
2. Change to the new `website` directory. Rename the default `origin` remote
to `upstream`.
```bash
cd website
git remote rename origin upstream
```
3. If you have not done so, create a fork of the repository on Github. In your
web browser, go to
[https://github.com/kubernetes/website](https://github.com/kubernetes/website)
and click the **Fork** button. After a few seconds, you are redirected to
the URL for your fork, which is typically something like
`https://github.com/<username>/website` unless you already had a repository
called `website`. Copy this URL.
4. Add your fork as a second remote, called `origin`:
```bash
git remote add origin <FORK-URL>
```
### Work on the local repository
Before you start a new unit of work on your local repository, you need to figure
out which branch to base your work on. The answer depends on what you are doing,
but the following guidelines apply:
- For general improvements to existing content, start from `master`.
- For new content that is about features that already exist in a released
version of Kubernetes, start from `master`.
- For long-running efforts that multiple SIG Docs contributors will collaborate on,
such as content reorganization, use a specific feature branch created for that
effort.
- For new content that relates to upcoming but unreleased Kubernetes versions,
use the pre-release feature branch created for that Kubernetes version.
For more guidance, see
[Choose which branch to use](docs/contribute/start#choose-which-git-branch-to-use).
After you decide which branch to start your work (or _base it on_, in Git
terminology), use the following workflow to be sure your work is based on the
most up-to-date version of that branch.
1. Fetch both the `upstream` and `origin` branches. This updates your local
notion of what those branches contain, but does not change your local
branches at all.
```bash
git fetch upstream
git fetch origin
```
2. Create a new tracking branch based on the branch you decided is the most
appropriate. This example assumes you are using `master`.
```bash
git checkout -b <my_new_branch> upstream/master
```
This new branch is based on `upstream/master`, not your local `master`.
It tracks `upstream/master`.
3. With your new branch checked out, make your changes using a text editor.
At any time, use the `git status` command to see what you've changed.
4. When you are ready to submit a pull request, commit your changes. First
use `git status` to see what changes need to be added to the changeset.
There are two important sections: `Changes staged for commit` and
`Changes not staged for commit`. Any files that show up in the latter
section under `modified` or `untracked` need to be added if you want them to
be part of this commit. For each file that needs to be added, use `git add`.
```bash
git add example-file.md
```
When all your intended changes are included, create a commit, using the
`git commit` command:
```bash
git commit -m "Your commit message"
```
{{< note >}}
Do not reference a Github issue or pull request by ID or URL in the
commit message. If you do, it will cause that issue or pull request to get
a notification every time the commit shows up in a new Git branch. You can
link issues and pull requests together later, in the Github UI.
{{< /note >}}
5. Optionally, you can test your change by staging the site locally using the
`hugo` command. See [View your changes locally](#view-your-changes-locally).
You'll be able to view your changes after you submit the pull request, as
well.
6. Before you can create a pull request which includes your local commit, you
need to push the branch to your fork, which is the endpoint for the `origin`
remote.
```bash
git push origin <my_new_branch>
```
Technically, you can omit the branch name from the `push` command, but
the behavior in that case depends upon the version of Git you are using.
The results are more repeatable if you include the branch name.
7. At this point, if you go to https://github.com/kubernetes/website in your
web browser, Github detects that you pushed a new branch to your fork and
offers to create a pull request. Fill in the pull request template.
- The title should be no more than 50 characters and summarize the intent
of the change.
- The long-form description should contain more information about the fix,
including a line like `Fixes #12345` if the pull request fixes a Github
issue. This will cause the issue to be closed automatically when the
pull request is merged.
- You can add labels or other metadata and assign reviewers. See
[Triage and categorize issues](#triage-and-categorize-issues) for the
syntax.
Click **Create pull request**.
8. Several automated tests will run against the state of the website with your
changes applied. If any of the tests fails, click the **Details** link for
more information. If the Netlify test completes successfully, its
**Details** link goes to a staged version of the Kubernetes website with
your changes applied. This is how reviewers will check your changes.
9. If you notice that more changes need to be made, or if reviewers give you
feedback, address the feedback locally, then repeat step 4 - 6 again,
creating a new commit. The new commit is added to your pull request and the
tests run again, including re-staging the Netlify staged site.
10. If a reviewer adds changes to your pull request, you need to fetch those
changes from your fork before you can add more changes. Use the following
commands to do this, assuming that your branch is currently checked out.
```bash
git fetch origin
git rebase origin/<your-branch-name>
```
After rebasing, you need to add the `-f` flag to force-push new changes to
the branch to your fork.
```bash
git push -f origin <your-branch-name>
```
11. If someone else's change is merged into the branch your work is based on,
and you have made changes to the same parts of the same files, a conflict
might occur. If the pull request shows that there are conflicts to resolve,
you can resolve them using the Github UI or you can resolve them locally.
First, do step 10 to be sure that your fork and your local branch are in
the same state.
Next, fetch `upstream` and rebase your branch on the branch it was
originally based on, like `upstream/master`.
```bash
git fetch upstream
git rebase upstream/master
```
If there are conflicts Git can't automatically resolve, you can see the
conflicted files using the `git status` command. For each conflicted file,
edit it and look for the conflict markers `>>>`, `<<<`, and `===`. Resolve
the conflict and remove the conflict markers. Then add the changes to the
changeset using `git add <filename>` and continue the rebase using
`git rebase --continue`. When all commits have been applied and there are
no more conflicts, `git status` will show that you are not in a rebase and
there are no changes that need to be committed. At that point, force-push
the branch to your fork, and the pull request should no longer show any
conflicts.
If you're having trouble resolving conflicts or you get stuck with
anything else related to your pull request, ask for help on the `#sig-docs`
Slack channel or the
[kubernetes-sig-docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs).
### View your changes locally
If you aren't ready to create a pull request but you want to see what your
changes look like, you can use the `hugo` command to stage the changes locally.
1. Install Hugo version `0.40.3` or later.
2. In a terminal, go to the root directory of your clone of the Kubernetes
docs, and enter this command:
```bash
hugo server
```
3. In your browser’s address bar, enter `localhost:1313`.
4. To stop the local Hugo instance, go back to the terminal and type `Ctrl+C`
or just close the terminal window.
## Triage and categorize issues
In any given week, a specific docs approver volunteers to do initial
[triage and review of pull requests](#review-pull-requests) and issues. To get
on this list, attend the weekly SIG Docs meeting and volunteer. Even if you are
not on the schedule for the current week, you can still review PRs.
People in SIG Docs are only responsible for triaging and categorizing
documentation issues. General website issues are also filed in the
`kubernetes/website` repository.
When you triage an issue, you:
- Assess whether the issue has merit. Some issues can be closed quickly by
answering a question or pointing the reporter to a resource.
- Ask the reporter for more information if the issue doesn't have enough
detail to be actionable or the template is not filled out adequately.
- Add labels (sometimes called tags), projects, or milestones to the issue.
Projects and milestones are not heavily used by the SIG Docs team.
- At your discretion, taking ownership of an issue and submitting a PR for it
(especially if it is quick or relates to work you were already doing).
If you have questions about triaging an issue, ask in `#sig-docs` on Slack or
the
[kubernetes-sig-docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs).
### More about labels
These guidelines are not set in stone and are subject to change.
- An issue can have multiple labels.
- Some labels use slash notation for grouping, which can be thought of like
"sub-labels". For instance, many `sig/` labels exist, such as `sig/cli` and
`sig/api-machinery`.
- Some labels are automatically added based on metadata in the files involved
in the issue, slash commands used in the comments of the issue, or
information in the issue text.
- Some labels are manually added by the person triaging the issue (or the person
reporting the issue, if they are a SIG Docs approvers).
- `Actionable`: there seems to be enough information for the issue to be fixed
or acted upon.
- `good first issue`: Someone with limited Kubernetes or SIG Docs experience
might be able to tackle this issue.
- `kind/bug`, `kind/feature`, and `kind/documentation`: If the person who
filed the issue did not fill out the template correctly, these labels may
not be assigned automatically. A bug is a problem with existing content or
functionality, and a feature is a request for new content or functionality.
The `kind/documentation` label is not currently in use.
- Priority labels: define the relative severity of the issue. These do not
conform to those outlined in the
[Kubernetes contributor guide](https://github.com/kubernetes/community/blob/master/contributors/guide/issue-triage.md#define-priority), and can be one of `P1`, `P2`, or `P3`, if set.
- To add a label, you can use Github's **Labels** widget if you are a Sig Docs
approver. Anyone who is a member of the Kubernetes organization can add a
label by leaving a comment like `/label <label-to-add>`. The label must
already exist. If you try to add a label that does not exist, the command is
silently ignored.
### Priorities
An issue's priority influences how quickly it is addressed. For documentation,
here are the guidelines for setting a priority on an issue:
#### P1
- Major content errors affecting more than 1 page
- Broken code sample on a heavily trafficked page
- Errors on a “getting started” page
- Well known or highly publicized customer pain points
- Automation issues
#### P2
This is the default for new issues and pull requests.
- Broken code for sample that is not heavily used
- Minor content issues in a heavily trafficked page
- Major content issues on a lower-trafficked page
#### P3
- Typos and broken anchor links
- Documentation feature requests
- "Nice to have" items
### Handling special issue types
We've encountered the following types of issues often enough to document how
to handle them.
#### Duplicate issues
If a single problem has one or more issues open for it, the problem should be
consolidated into a single issue. You should decide which issue to keep open (or
open a new issue), port over all relevant information, link related issues, and
close all the other issues that describe the same problem. Only having a single
issue to work on will help reduce confusion and avoid duplicating work on the
same problem.
#### Dead link issues
Depending on where the dead link is reported, different actions are required to
resolve the issue. Dead links in the API and Kubectl docs are automation issues
and should be assigned a P1 until the problem can be fully understood. All other
dead links are issues that need to be manually fixed and can be assigned a P3.
#### Support requests or code bug reports
Some issues opened for docs are instead issues with the underlying code, or
requests for assistance when something (like a tutorial) didn’t work. For issues
unrelated to docs, close the issue with a comment directing the requester to
support venues (Slack, Stack Overflow) and, if relevant, where to file an issue
for bugs with features (kubernetes/kubernetes is a great place to start).
Sample response to a request for support:
```none
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
resources like
[Stack Overflow](http://stackoverflow.com/questions/tagged/kubernetes)
for answers to similar questions.
You can also open issues for Kubernetes functionality in
https://github.com/kubernetes/kubernetes.
If this is a documentation issue, please re-open this issue.
```
Sample code bug report response:
```none
This sounds more like an issue with the code than an issue with
the documentation. Please open an issue at
https://github.com/kubernetes/kubernetes/issues.
If this is a documentation issue, please re-open this issue.
```
## Document new features
Each major Kubernetes release includes new features, and many of them need
at least a small amount of documentation to show people how to use them.
Often, the SIG responsible for a feature submits draft documentation for the
feature as a pull request to the appropriate release branch of
`kubernetes/website` repository, and someone on the SIG Docs team provides
editorial feedback or edits the draft directly.
### Find out about upcoming features
To find out about upcoming features, attend the weekly sig-release meeting (see
the [community](https://kubernetes.io/community/) page for upcoming meetings)
and monitor the release-specific documentation
in the [kubernetes/sig-release](https://github.com/kubernetes/sig-release/)
repository. Each release has a sub-directory under the [/sig-release/tree/master/releases/](https://github.com/kubernetes/sig-release/tree/master/releases)
directory. Each sub-directory contains a release schedule, a draft of the release
notes, and a document listing each person on the release team.
- The release schedule contains links to all other documents, meetings,
meeting minutes, and milestones relating to the release. It also contains
information about the goals and timeline of the release, and any special
processes in place for this release. Near the bottom of the document, several
release-related terms are defined.
This document also contains a link to the **Feature tracking sheet**, which is
the official way to find out about all new features scheduled to go into the
release.
- The release team document lists who is responsible for each release role. If
it's not clear who to talk to about a specific feature or question you have,
either attend the release meeting to ask your question, or contact the release
lead so that they can redirect you.
- The release notes draft is a good place to find out a little more about
specific features, changes, deprecations, and more about the release. The
content is not finalized until late in the release cycle, so use caution.
#### The feature tracking sheet
The feature tracking sheet
[for a given Kubernetes release](https://github.com/kubernetes/sig-release/tree/master/releases) lists each feature that is planned for a release.
Each line item includes the name of the feature, a link to the feature's main
Github issue, its stability level (Alpha, Beta, or Stable), the SIG and
individual responsible for implementing it, whether it
needs docs, a draft release note for the feature, and whether it has been
merged. Keep the following in mind:
- Beta and Stable features are generally a higher documentation priority than
Alpha features.
- It's hard to test (and therefore, document) a feature that hasn't been merged,
or is at least considered feature-complete in its PR.
- Determining whether a feature needs documentation is a manual process and
just because a feature is not marked as needing docs doesn't mean it doesn't
need them.
### Document a feature
As stated above, draft content for new features is usually submitted by the SIG
responsible for implementing the new feature. This means that your role may be
more of a shepherding role for a given feature than developing the documentation
from scratch.
After you've chosen a feature to document/shepherd, ask about it in the `#sig-docs`
Slack channel, in a weekly sig-docs meeting, or directly on the PR filed by the
feature SIG. If you're given the go-ahead, you can edit into the PR using one of
the techniques described in
[Commit into another person's PR](#commit-into-another-persons-pr).
If you need to write a new topic, the following links are useful:
- [Writing a New Topic](/docs/contribute/style/write-new-topic/)
- [Using Page Templates](/docs/contribute/style/page-templates/)
- [Documentation Style Guide](/docs/contribute/style/style-guide/)
### SIG members documenting new features
If you are a member of a SIG developing a new feature for Kubernetes, you need
to work with SIG Docs to be sure your feature is documented in time for the
release. Check the
[feature tracking spreadsheet](https://github.com/kubernetes/sig-release/tree/master/releases)
or check in the #sig-release Slack channel to verify scheduling details and
deadlines. Some deadlines related to documentation are:
- **Docs deadline - Open placeholder PRs**: Open a pull request against the
`release-X.Y` branch in the `kubernetes/website` repository, with a small
commit that you will amend later. Use the Prow command `/milestone X.Y` to
assign the PR to the relevant milestone. This alerts the docs person managing
this release that the feature docs are coming. If your feature does not need
any documentation changes, make sure the sig-release team knows this, by
mentioning it in the #sig-release Slack channel. If the feature does need
documentation but the PR is not created, the feature may be removed from the
milestone.
- **Docs deadline - PRs ready for review**: Your PR now needs to contain a first
draft of the documentation for your feature. Don't worry about formatting or
polishing. Just describe what the feature does and how to use it. The docs
person managing the release will work with you to get the content into shape
to be published. If your feature needs documentation and the first draft
content is not received, the feature may be removed from the milestone.
- **Docs complete - All PRs reviewed and ready to merge**: If your PR has not
yet been merged into the `release-X.Y` branch by this deadline, work with the
docs person managing the release to get it in. If your feature needs
documentation and the docs are not ready, the feature may be removed from the
milestone.
## Contribute to other repos
The [Kubernetes project](https://github.com/kubernetes) contains more than 50
individual repositories. Many of these repositories contain code or content that
can be considered documentation, such as user-facing help text, error messages,
user-facing text in API references, or even code comments.
If you see text and you aren't sure where it comes from, you can use Github's
search tool at the level of the Kubernetes organization to search through all
repositories for that text. This can help you figure out where to submit your
issue or PR.
Each repository may have its own processes and procedures. Before you file an
issue or submit a PR, read that repository's `README.md`, `CONTRIBUTING.md`, and
`code-of-conduct.md`, if they exist.
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.
## Localize content
The Kubernetes documentation is written in English first, but we want people to
be able to read it in their language of choice. If you are comfortable
writing in another language, especially in the software domain, you can help
localize the Kubernetes documentation or provide feedback on existing localized
content. See [Localization](/docs/contribute/localization/) and ask on the
[kubernetes-sig-docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs)
or in `#sig-docs` on Slack if you are interested in helping out.
{{% /capture %}}
{{% capture whatsnext %}}
When you are comfortable with all of the tasks discussed in this topic and you
want to engage with the Kubernetes docs team in even deeper ways, read the
[advanced docs contributor](/docs/contribute/advanced/) topic.
{{% /capture %}}
content/en/docs/contribute/localization.md
+149
View File
@@ -0,0 +1,149 @@
---
title: Localizing Kubernetes Documentation
content_template: templates/concept
approvers:
- chenopis
- zacharysarah
---
{{% capture overview %}}
The Kubernetes documentation is currently available in [multiple languages](#supported-languages) and we encourage you to add new localizations ([l10n](https://blog.mozilla.org/l10n/2011/12/14/i18n-vs-l10n-whats-the-diff/))!
Currently available languages:
{{< language-repos-list >}}
In order for localizations to be accepted, however, they must fulfill some requirements related to workflow (*how* to localize) and output (*what* to localize).
{{% /capture %}}
{{< toc >}}
{{% capture body %}}
## Workflow
The Kubernetes documentation for all languages is built from the [kubernetes/website](https://github.com/kubernetes/website) repository on GitHub. Most day-to-work work on translations, however, happens in separate translation repositories. Changes to those repositories are then [periodically](#upstream-contributions) synced to the main kubernetes/website repository via [pull request](../create-pull-request).
Work on the Chinese translation, for example, happens in the [kubernetes/kubernetes-docs-zh](https://github.com/kubernetes/kubernetes-docs-zh) repository.
{{< note >}}
**Note**: For an example localization-related [pull request](../create-pull-request), see [this pull request](https://github.com/kubernetes/website/pull/8636) to the [Kubernetes website repo](https://github.com/kubernetes/website) adding Korean localization to the Kubernetes docs.
{{< /note >}}
## Source Files
Localizations must use English files from the most recent major release as sources. To find the most recent release's documentation source files:
1. Navigate to the Kubernetes website repository at https://github.com/kubernetes/website.
2. Select the `release-1.X` branch for the most recent version, which is currently **{{< latest-version >}}**, making the most recent release branch [`{{< release-branch >}}`](https://github.com/kubernetes/website/tree/{{< release-branch >}}).
## Getting started
In order to add a new localization of the Kubernetes documentation, you'll need to make a few modifications to the site's [configuration](#configuration) and [directory structure](#new-directory), and then you can get to work [translating documents](#translating-documents)!
To get started, clone the website repo and `cd` into it:
```shell
git clone https://github.com/kubernetes/website
cd website
git checkout {{< release-branch >}}
```
## Configuration
We'll walk you through the configuration process using the German language (language code `de`) as an example.
There's currently no translation for German, but you're welcome to create one using the instructions here.
The Kubernetes website's configuration is in the [`config.toml`](https://github.com/kubernetes/website/tree/master/config.toml) file. You need to add a configuration block for the new language to that file, under the existing `[languages]` block. The German block, for example, looks like this:
```toml
[languages.de]
title = "Kubernetes"
description = "Produktionsreife Container-Verwaltung"
languageName = "Deutsch"
contentDir = "content/de"
weight = 3
```
When assigning a `weight` parameter, see which of the current languages has the highest weight and add 1 to that value.
Now add a language-specific subdirectory to the [`content`](https://github.com/kubernetes/website/tree/master/content) folder. The two-letter code for German is `de`, so add a `content/de` directory:
```shell
mkdir content/de
```
## Translating documents
We understand that localizing *all* of the Kubernetes documentation would be an enormous task. We're okay with localizations smarting small and expanding over time.
As an initial requirement, all localizations must include the following documentation at a minimum:
Description | URLs
-----|-----
Home | [All heading and subheading URLs](https://kubernetes.io/docs/home/)
Setup | [All heading and subheading URLs](https://kubernetes.io/docs/setup/)
Tutorials | [Kubernetes Basics](https://kubernetes.io/docs/tutorials/kubernetes-basics/), [Hello Minikube](https://kubernetes.io/docs/tutorials/stateless-application/hello-minikube/)
Translated documents should have the same URL endpoint as the English docs (substituting the subdirectory of the `content` folder). To translate the [Kubernetes Basics](https://kubernetes.io/docs/tutorials/kubernetes-basics/) doc into German, for example, create the proper subfolder under the `content/de` folder and copy the English doc:
```shell
mkdir -p content/de/docs/tutorials
cp content/en/docs/tutorials/kubernetes-basics.md content/de/docs/tutorials/kubernetes-basics.md
```
## Project logistics
### Contact with project chairs
When starting a new localization effort, you should get in touch with one of the chairs of the Kubernetes [SIG Docs](https://github.com/kubernetes/community/tree/master/sig-docs) organization. The current chairs are listed [here](https://github.com/kubernetes/community/tree/master/sig-docs#chairs).
### Project information
Teams working on localization efforts must provide a single point of contact, including the name and contact information of a person who can respond to or redirect questions or concerns, listed in the translation repository's main [`README`](https://help.github.com/articles/about-readmes/). You can provide an email address, email list, [Slack channel](https://slack.com/), or some other method of contact.
### Maintainers
Each localization repository must select its own maintainers. Maintainers can be from a single organization or multiple organizations.
In addition, all l10n work must be self-sustaining with the team's own resources.
Wherever possible, every localized page must be approved by a reviewer from a different company than the translator.
### GitHub project
Each Kubernetes localization repository must track its overall progress with a [GitHub project](https://help.github.com/articles/creating-a-project-board/).
Projects must include at least these columns:
- To Do
- In Progress
- Done
{{< note >}}
**Note**: For an example GitHub project, see the [Chinese localization project](https://github.com/kubernetes/kubernetes-docs-zh/projects/1).
{{< /note >}}
### Repository structure
Each l10n repository must have branches for the different Kubernetes documentation release versions, matching the branches in the main [kubernetes/website](https://github.com/kubernetes/website) documentation repository. For example, the kubernetes/website `release-1.10` branch (https://github.com/kubernetes/website/tree/release-1.10) has a corresponding branch in the kubernetes/kubernetes-docs-zh repository (https://github.com/kubernetes/kubernetes-docs-zh/tree/release-1.10). These version branches keep track of the differences in the documentation between Kubernetes versions.
### Upstream contributions
Upstream contributions are welcome and encouraged!
For the sake of efficiency, limit upstream contributions to a single pull request per week, containing a single [squashed commit](https://github.com/todotxt/todo.txt-android/wiki/Squash-All-Commits-Related-to-a-Single-Issue-into-a-Single-Commit).
{{% /capture %}}
{{% capture whatsnext %}}
Once a l10n meets requirements for workflow and minimum output, SIG docs will:
- Work with the localization team to implement language selection on the website.
- Publicize availability through [Cloud Native Computing Foundation](https://www.cncf.io/) (CNCF) channels.
{{% /capture %}}
content/en/docs/contribute/participating.md
+219
View File
@@ -0,0 +1,219 @@
---
title: Participating in SIG Docs
content_template: templates/concept
---
{{% capture overview %}}
SIG Docs is one of the
[special interest groups](https://github.com/kubernetes/community/blob/master/sig-list.md)
within the Kubernetes project, focused on writing, updating, and maintaining
the documentation for Kubernetes as a whole. See
[SIG Docs from the community github repo](https://github.com/kubernetes/community/tree/master/sig-docs)
for more information about the SIG.
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.
Within SIG Docs, you may also become a [member](#members),
[reviewer](#reviewers), or [approver](#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.
{{% /capture %}}
{{% capture body %}}
## Roles and responsibilities
When a pull request is merged to the branch used to publish content (currently
`master`), that content is published and available to the world. To ensure that
the quality of our published content is high, we limit merging pull requests to
SIG Docs approvers. Here's how it works.
- When a pull request has both the `lgtm` and `approve` labels and has no `hold`
labels, the pull request merges automatically.
- Kubernetes organization members and SIG Docs approvers can add comments to
prevent automatic merging of a given pull request (by adding a `/hold` comment
or withholding a `/lgtm` comment).
- Any Kubernetes member can add the `lgtm` label, by adding a `/lgtm` comment.
- Only an approver who is a member of SIG Docs can cause a pull request to merge
by adding an `/approve` comment. Some approvers also perform additional
specific roles, such as [PR Wrangler](#pr-wrangler) or
[SIG Docs chairperson](#sig-docs-chairperson).
For more information about expectations and differences between the roles of
Kubernetes organization member and SIG Docs approvers, see
[Types of contributor](/docs/contribute#types-of-contributor). The following
sections cover more details about these roles and how they work within
SIG Docs.
### Anyone
Anyone can file an issue against any part of Kubernetes, including documentation.
Anyone who has signed the CLA can submit a pull request. If you cannot sign the
CLA, the Kubernetes project cannot accept your contribution.
### Members
Any member of the [Kubernetes organization](https://github.com/kubernetes) can
review a pull request, and SIG Docs team members frequently request reviews from
members of other SIGs for technical accuracy.
SIG Docs also welcomes reviews and feedback regardless of a person's membership
status in the Kubernetes organization. You can indicate your approval by adding
a comment of `/lgtm` to a pull request. If you are not a member of the
Kubernetes organization, your `/lgtm` has no effect on automated systems.
Any member of the Kubernetes organization can add a `/hold` comment to prevent
the pull request from being merged. Any member can also remove a `/hold` comment
to cause a PR to be merged if it already has both `/lgtm` and `/approve` applied
by appropriate people.
### Reviewers
Reviewers are members of the
[@kubernetes/sig-docs-pr-reviews](https://github.com/orgs/kubernetes/teams/sig-docs-pr-reviews)
Github group. See [Teams and groups within SIG Docs](#teams-and-groups-within-sig-docs).
Reviewers review documentation pull requests and provide feedback on proposed
changes.
Automation assigns reviewers to pull requests, and contributors can request a
review from a specific reviewer with a comment on the pull request: `/assign
[@_github_handle]`. To indicate that a pull request is technically accurate and
requires no further changes, a reviewer adds a `/lgtm` comment to the pull
request.
If the assigned reviewer has not yet reviewed the content, another reviewer can
step in. In addition, you can assign technical reviewers and wait for them to
provide `/lgtm`.
For a trivial change or one that needs no technical review, the SIG Docs
[approver](#approvers) can provide the `/lgtm` as well.
A `/approve` comment from a reviewer is ignored by automation.
For more about how to become a SIG Docs reviewer and the responsibilities and
time commitment involved, see
[Becoming a reviewer or approver](#becoming-an-approver-or-reviewer).
### Approvers
Approvers are members of the
[@kubernetes/sig-docs-maintainers](https://github.com/orgs/kubernetes/teams/sig-docs-maintainers)
Github group. See [Teams and groups within SIG Docs](#teams-and-groups-within-sig-docs).
Approvers have the ability to merge a PR, and thus, to publish content on the
Kubernetes website. To approve a PR, an approver leaves an `/approve` comment on
the PR. If someone who is not an approver leaves the approval comment,
automation ignores it.
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.
For more about how to become a SIG Docs approver and the responsibilities and
time commitment involved, see
[Becoming a reviewer or approver](#becoming-an-approver-or-reviewer).
#### PR Wrangler
SIG Docs approvers are added to the
[PR Wrangler rotation scheduler](https://github.com/kubernetes/website/wiki/PR-Wranglers)
for weekly rotations. All SIG Docs approvers are expected to take part in this
rotation. See
[Be the PR Wrangler for a week](/docs/contribute/advanced#be-the-pr-wrangler-for-a-week)
for more details.
#### SIG Docs chairperson
Each SIG, including SIG Docs, selects one or more SIG members to act as
chairpersons. These are points of contact between SIG Docs and other parts of
the Kubernetes organization. They require extensive knowledge of the structure
of the Kubernetes project as a whole and how SIG Docs works within it. See
[Leadership](https://github.com/kubernetes/community/tree/master/sig-docs#leadership)
for the current list of chairpersons.
## SIG Docs teams and automation
Automation in SIG Docs relies on two different mechanisms for automation:
Github groups and OWNERS files.
### Github groups
The SIG Docs group defines two teams on Github:
- [@kubernetes/sig-docs-maintainers](https://github.com/orgs/kubernetes/teams/sig-docs-maintainers)
- [@kubernetes/sig-docs-pr-reviews](https://github.com/orgs/kubernetes/teams/sig-docs-pr-reviews)
Each can be referenced with their `@name` in Github comments to communicate with
everyone in that group.
These teams overlap, but do not exactly match, the groups used by the automation
tooling. For assignment of issues, pull requests, and to support PR approvals,
the automation uses information from OWNERS files.
### OWNERS files and front-matter
The Kubernetes project uses an automation tool called prow for automation
related to Github issues and pull requests. The
[Kubernetes website repository](https://github.com/kubernetes/website) uses
two [prow plugins](https://github.com/kubernetes/test-infra/blob/master/prow/plugins.yaml#L210):
- blunderbuss
- approve
These two plugins use the
[OWNERS](https://github.com/kubernetes/website/blob/master/OWNERS) and
[OWNERS_ALIASES](https://github.com/kubernetes/website/blob/master/OWNERS_ALIASES)
files in the top level of the `kubernetes/website` Github repository to control
how prow works within the repository.
An OWNERS file contains a list of people who are SIG Docs reviewers and
approvers. OWNERS files can also exist in subdirectories, and can override who
can act as a reviewer or approver of files in that subdirectory and its
descendents. For more information about OWNERS files in general, see
[OWNERS](https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md).
In addition, an individual Markdown file can list reviewers and approvers in its
front-matter, either by listing individual Github usernames or Github groups.
The combination of OWNERS files and front-matter in Markdown files determines
the advice PR owners get from automated systems about who to ask for technical
and editorial review of their PR.
## Become a reviewer or approver
To volunteer as a reviewer or approver, make sure you
[meet the general requirements](https://github.com/kubernetes/community/blob/master/community-membership.md#membership)
and the [requirements for SIG Docs](#become-a-reviewer-or-approver). Your
SIG Docs sponsor adds you to the appropriate Github groups and OWNERS files
after your status as a reviewer or approver is approved by the SIG.
| Role | SIG Docs prerequisites | Responsibilities |
|------------------------|---------------------------------------------------|-----------------------------------------------------------|
| [Member](#members) | Sign the CLA | Follow the [Code of Conduct](/community/#code-of-conduct) |
| [Reviewer](#reviewers) | Regularly participate in weekly SIG Docs meetings | Review PRs auto-assigned by blunderbuss within 1 week |
| [Approver](#approvers) | <ul><li>Contribute regularly as a reviewer for at least 3 months</li><li>Understand SIG Docs workflows and tooling</li></ul> | <ul><li>Respond to PR comments/requests for review from other maintainers within 1 week</li><li>Serve periodically as the PR Wrangler for SIG Docs</li></ul> |
{{% /capture %}}
{{% capture whatsnext %}}
For more information about contributing to the Kubernetes documentation, see:
- [Start contributing](/docs/contribute/start/)
- [Documentation style](/docs/contribute/style/)
{{% /capture %}}
content/en/docs/contribute/start.md
+355
View File
@@ -0,0 +1,355 @@
---
title: Start contributing
slug: start
content_template: templates/concept
weight: 10
---
{{% capture overview %}}
If you want to get started contributing to the Kubernetes documentation, this
page and its linked topics can help you get started. You don't need to be a
developer or a technical writer to make a big impact on the Kubernetes
documentation and user experience! All you need for the topics on this page is
a [Github account](https://github.com/join) and a web browser.
If you're looking for information on how to start contributing to Kubernetes
code repositories, refer to
[the Kubernetes community guidelines](https://github.com/kubernetes/community/blob/master/governance.md).
{{% /capture %}}
{{% capture body %}}
## The basics about our docs
The Kubernetes documentation is written in Markdown and processed and deployed
using Hugo. The source is in Github at
[https://github.com/kubernetes/website](https://github.com/kubernetes/website).
Most of the documentation source is stored in `/content/en/docs/`. Some of the
reference documentation is automatically generated from scripts, mostly in the
`/content/en/docs/imported/` subdirectory.
You can file issues, edit content, and review changes from others, all from the
Github website. You can also use Github's embedded history and search tools.
Not all tasks can be done in the Github UI, but these are discussed in the
[intermediate](/docs/contribute/intermediate/) and
[advanced](/docs/contribute/advanced/) docs contribution guides.
### Participating in SIG Docs
The Kubernetes documentation is maintained by a special interest group (SIG)
called Sig Docs. We communicate using a Slack channel, a mailing list, and
weekly video meetings. New participants are welcome. For more information, see
[Participating in SIG Docs](/docs/contribute/participating/).
### Style guidelines
We maintain a [style guide](/docs/contribute/style/style-guide/) with information
about choices the SIG Docs community has made about grammar, syntax, source
formatting, and typographic conventions. Look over the style guide before you
make your first contribution, and use it when you have questions.
Changes to the style guide are made by SIG Docs as a group. To propose a change
or addition, [add it to the agenda](https://docs.google.com/document/d/1Ds87eRiNZeXwRBEbFr6Z7ukjbTow5RQcNZLaSvWWQsE/edit#) for an upcoming SIG Docs meeting, and attend the meeting to participate in the
discussion. See the [advanced contribution](advanced.md) topic for more
information.
### Page templates
We use page templates to control the presentation of our documentation pages.
Be sure to understand how these templates work by reviewing
[Using page templates](/docs/contribute/style/page-templates/).
### Hugo shortcodes
The Kubernetes documentation is transformed from Markdown to HTML using Hugo.
We make use of the standard Hugo shortcodes, as well as a few that are custom to
the Kubernetes documentation. See [Custom Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/) for
information about how to use them.
## File actionable issues
Anyone with a Github account can file an issue (bug report) against the
Kubernetes documentation. If you see something wrong, even if you have no idea
how to fix it, [file an issue](#how-to-file-an-issue). The exception to this
rule is a tiny bug like a typo that you intend to fix yourself. In that case,
you can instead [fix it](#fix-it) without filing a bug first.
### How to file an issue
- **On an existing page**
If you see a problem in an existing page in the [Kubernetes docs](/docs/),
go to the bottom of the page and click the **Create an Issue** button. If
you are not currently logged in to Github, log in. A Github issue form
appears with some pre-populated content.
Using Markdown, fill in as many details as you can. In places where you see
empty square brackets (`[ ]`), put an `x` between the set of brackets that
represents the appropriate choice. If you have a proposed solution to fix
the issue, add it.
- **Request a new page**
If you think content should exist, but you aren't sure where it should go or
you don't think it fits within the pages that currently exist, you can
still file an issue. You can either choose an existing page near where you think the
new content should go and file the issue from that page, or go straight to
[https://github.com/kubernetes/website/issues/new/](https://github.com/kubernetes/website/issues/new/)
and file the issue from there.
### How to file great issues
To ensure that we understand your issue and can act on it, keep these guidelines
in mind:
- Use the issue template, and fill out as many details as you can.
- Clearly explain the specific impact the issue has on users.
- Limit the scope of a given issue to a reasonable unit of work. For problems
with a large scope, break them down into smaller issues.
For instance, "Fix the security docs" is not an actionable issue, but "Add
details to the 'Restricting network access' topic" might be.
- If the issue relates to another issue or pull request, you can refer to it
either by its full URL or by the the issue or pull request number prefixed
with a `#` character. For instance, `Introduced by #987654`.
- Be respectful and avoid venting. For instance, "The docs about X suck" is not
helpful or actionable feedback. The
[Code of Conduct](/community/code-of-conduct/) also applies to interactions on
Kubernetes Github repositories.
## Participate in SIG Docs discussions
The SIG Docs team communicates using the following mechanisms:
- [Join the Kubernetes Slack instance](http://slack.k8s.io/), then join the
`#sig-docs` channel, where we discuss docs issues in real-time. Be 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.
- Participate in the weekly SIG Docs video meeting, which is announced on the
Slack channel and the mailing list. Currently, these meetings take place on
Zoom, so you'll need to download the [Zoom client](https://zoom.us/download)
or dial in using a phone.
## Improve existing content
To improve existing content, you file a _pull request (PR)_ after creating a
_fork_. Those two terms are [specific to Github](https://help.github.com/categories/collaborating-with-issues-and-pull-requests/).
For the purposes of this topic, you don't need to know everything about them,
because you can do everything using your web browser. When you continue to the
[intermediate docs contributor guide](/docs/contribute/intermediate/), you will
need more background in Git terminology.
{{< note >}}
**Kubnetes code developers**: If you are documenting a new feature for an
upcoming Kubernetes release, your process is a bit different. See
[Document a feature](/docs/contribute/intermediate.md#sig-members-documenting-new-features) for
process guidelines and information about deadlines.
{{< /note >}}
### Sign the CLA
Before you can contribute code or documentation to Kubernetes, you **must** read
the [Contributor guide](/docs/imported/community/guide/) and
[sign the Contributor License Agreement (CLA)](/docs/imported/community/guide/#sign-the-cla).
Don't worry -- this doesn't take long!
### Find something to work on
If you see something you want to fix right away, just follow the instructions
below. You don't need to [file an issue](#file-actionable-issues) (although you
certainly can).
If you want to start by finding an existing issue to work on, go to
[https://github.com/kubernetes/website/issues](https://github.com/kubernetes/website/issues)
and look for issues with the label `good first issue` (you can use
[this](https://github.com/kubernetes/website/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) shortcut). Read through the comments and make sure there is not an open pull
request against the issue and that nobody has left a comment saying they are
working on the issue recently (3 days is a good rule). Leave a comment saying
that you would like to work on the issue.
### Choose which Git branch to use
The most important aspect of submitting pull requests is choosing which branch
to base your work on. Use these guidelines to make the decision:
- Use `master` for fixing problems in content that is already published, or
making improvements to content that already exists.
- Use a release branch (such as `release-1.12`) to document upcoming features
or changes for an upcoming release that is not yet published.
- Use a feature branch that has been agreed upon by SIG Docs to collaborate on
big improvements or changes to the existing documentation, including content
reorganization or changes to the look and feel of the website.
If you're still not sure which branch to choose, ask in `#sig-docs` on Slack or
attend a weekly SIG Docs meeting to get clarity.
### Submit a pull request
Follow these steps to submit a pull request to improve the Kubernetes
documentation.
1. On the page where you see the issue, click the pencil icon at the top left.
A new page appears, with some help text.
2. Click the first blue button, which has the text **Edit <page name>**.
If you have never created a fork of the Kubernetes documentation
repository, you are prompted to do so. Create the fork under your Github
username, rather than another organization you may be a member of. The
fork usually has a URL such as `https://github.com/<username>/website`,
unless you already have a repository with a conflicting name.
The reason you are prompted to create a fork is that you do not have
access to push a branch directly to the definitive Kubernetes repository.
3. The Github Markdown editor appears with the source Markdown file loaded.
Make your changes. Below the editor, fill in the **Propose file change**
form. The first field is the summary of your commit message and should be
no more than 50 characters long. The second field is optional, but can
include more detail if appropriate.
{{< note >}}
**Note**: Do not include references to other Github issues or pull
requests in your commit message. You can add those to the pull request
description later.
{{< /note >}}
Click **Propose file change**. The change is saved as a commit in a
new branch in your fork, which is automatically named something like
`patch-1`.
4. The next screen summarizes the changes you made, by comparing your new
branch (the **head fork** and **compare** selection boxes) to the current
state of the **base fork** and **base** branch (`master` on the
`kubernetes/website` repository by default). You can change any of the
selection boxes, but don't do that now. Have a look at the difference
viewer on the bottom of the screen, and if everything looks right, click
**Create pull request**.
{{< note >}}
**Note**: If you don't want to create the pull request now, you can do it
later, by browsing to the main URL of the Kubernetes website repository or
your fork's repository. The Github website will prompt you to create the
pull request if it detects that you pushed a new branch to your fork.
{{< /note >}}
5. The **Open a pull request** screen appears. The subject of the pull request
is the same as the commit summary, but you can change it if needed. The
body is populated by your extended commit message (if present) and some
template text. Read the template text and fill out the details it asks for,
then delete the extra template text. Leave the
**Allow edits from maintainers** checkbox selected. Click
**Create pull request**.
Congratulations! Your pull request is available in
Pull requests](https://github.com/kubernetes/website/pulls).
After a few minutes, you can preview the website with your PR's changes
applied. Go to the **Conversation** tab of your PR and click the **Details**
link for the `deploy/netlify` test, near the bottom of the page. It opens in
the same browser window by default.
6. Wait for review. Generally, reviewers are suggested by the `k8s-ci-robot`.
If a reviewer asks you to make changes, you can go to the **Files changed**
tab and click the pencil icon on any files that have been changed by the
pull request. When you save the changed file, a new commit is created in
the branch being monitored by the pull request.
7. If your change is accepted, a reviewer merges your pull request, and the
change is live on the Kubernetes website a few minutes later.
This is only one way to submit a pull request. If you are already a Git and
Github advanced user, you can use a local GUI or command-line Git client
instead of using the Github UI. Some basics about using the command-line Git
client are discussed in the [intermediate](/docs/contribute/intermediate/) docs
contribution guide.
## Review docs pull requests
People who are not yet approvers or reviewers can still review pull requests.
The reviews are not considered "binding", which means that your review alone
won't cause a pull request to be merged. However, it can still be helpful. Even
if you don't leave any review comments, you can get a sense of pull request
conventions and etiquette and get used to the workflow.
1. Go to
[https://github.com/kubernetes/website/pulls](https://github.com/kubernetes/website/pulls).
You see a list of every open pull request against the Kubernetes website and
docs.
2. By default, the only filter that is applied is `open`, so you don't see
pull requests that have already been closed or merged. It's a good idea to
apply the `cncf-cla: yes` filter, and for your first review, it's a good
idea to add `size/S` or `size/XS`. The `size` label is applied automatically
based on how many lines of code the PR modifies. You can apply filters using
the selection boxes at the top of the page, or use
[this shortcut](https://github.com/kubernetes/website/pulls?q=is%3Aopen+is%3Apr+label%3A%22cncf-cla%3A+yes%22+label%3Asize%2FS) for only small PRs. All filters are `AND`ed together, so
you can't search for both `size/XS` and `size/S` in the same query.
3. Go to the **Files changed** tab. Look through the changes introduced in the
PR, and if applicable, also look at any linked issues. If you see a problem
or room for improvement, hover over the line and click the `+` symbol that
appears.
You can type a comment, and either choose **Add single comment** or **Start
a review**. Typically, starting a review is better because it allows you to
leave multiple comments and notifies the PR owner only when you have
completed the review, rather than a separate notification for each comment.
4. When finished, click **Review changes** at the top of the page. You can
summarize your review, and you can choose to comment, approve, or request
changes. New contributors should always choose **Comment**.
Thanks for reviewing a pull request! When you are new to the project, it's a
good idea to ask for feedback on your pull request reviews. The `#sig-docs`
Slack channel is a great place to do this.
## Write a blog post
Anyone can write a blog post and submit it for review. Blog posts should not be
commercial in nature and should consist of content that will apply broadly to
the Kubernetes community.
To submit a blog post, you can either submit it using the
[Kubernetes blog submission form](https://docs.google.com/forms/d/e/1FAIpQLSch_phFYMTYlrTDuYziURP6nLMijoXx_f7sLABEU5gWBtxJHQ/viewform),
or follow the steps below.
1. [Sign the CLA](#sign-the-cla) if you have not yet done so.
2. Have a look at the Markdown format for existing blog posts in the
[website repository](https://github.com/kubernetes/website/tree/master/content/en/blog/_posts).
3. Write out your blog post in a text editor of your choice.
4. On the same link from step 2, click the **Create new file** button. Paste
your content into the editor. Name the file to match the proposed title of
the blog post, but don't put the date in the file name. The blog reviewers
will work with you on the final file name and the date the blog will be
published.
5. When you save the file, Github will walk you through the pull request
process.
6. A blog post reviewer will review your submission and work with you on
feedback and final details. When the blog post is approved, the blog will be
scheduled for publication.
## Submit a case study
Case studies highlight how organizations are using Kubernetes to solve
real-world problems. They are written in collaboration with the Kubernetes
marketing team, which is handled by the CNCF.
Have a look at the source for the
[existing case studies](https://github.com/kubernetes/website/tree/master/content/en/case-studies).
Use the [Kubernetes case study submission form](https://www.cncf.io/people/end-user-community/)
to submit your proposal.
{{% /capture %}}
{{% capture whatsnext %}}
When you are comfortable with all of the tasks discussed in this topic and you
want to engage with the Kubernetes docs team in deeper ways, read the
[intermediate docs contribution guide](/docs/contribute/intermediate/).
{{% /capture %}}
content/en/docs/contribute/style/_index.md
+9
View File
@@ -0,0 +1,9 @@
---
title: Documentation style overview
main_menu: true
weight: 80
---
The topics in this section provide guidance on writing style, content formatting
and organization, and using Hugo customizations specific to Kubernetes
documentation.
content/en/docs/contribute/style/content-organization.md
+141
View File
@@ -0,0 +1,141 @@
---
title: Content organization
content_template: templates/concept
weight: 40
---
{{< toc >}}
{{% capture overview %}}
This site uses Hugo. In Hugo, [content organization](https://gohugo.io/content-management/organization/) is a core concept.
{{% /capture %}}
{{% capture body %}}
{{% note %}}
**Hugo Tip:** Start Hugo with `hugo server --navigateToChanged` for content edit-sessions.
{{% /note %}}
## Page Lists
### Page Order
The documentation side menu, the documentation page browser etc. are listed using Hugo's default sort order, which sorts by weight (from 1), date (newest first) and finally by the link title.
Given that, if you want to move a page or a section up, set a weight in the page's front matter:
```yaml
title: My Page
weight: 10
```
{{% note %}}
For page weights, it can be smart not to use 1, 2, 3 ..., but some other interval, say 10, 20, 30... This allows you to insert pages where you want later.
{{% /note %}}
### Documentation Main Menu
The `Documentation` main menu is built from the sections below `docs/` with the `main_menu` flag set in front matter of the `_index.md` section content file:
```yaml
main_menu: true
```
Note that the link title is fetched from the page's `linkTitle`, so if you want it to be something different than the title, change it in the content file:
```yaml
main_menu: true
title: Page Title
linkTitle: Title used in links
```
{{% note %}}
The above needs to be done per language. If you don't see your section in the menu, it is probably because it is not identified as a section by Hugo. Create a `_index.md` content file in the section folder.
{{% /note %}}
### Documentation Side Menu
The documentation side-bar menu is built from the _current section tree_ starting below `docs/`.
It will show all sections and their pages.
If you want a section or page to not be listed, set the `toc_hide` flag in front matter:
```yaml
toc_hide: true
```
When you navigate to a section, the page shown is the section page (e.g. `_index.md`) if it has content, else the first page inside that section.
### Documentation Browser
The page browser on the documentation home page is built from all sections and pages directly below the `docs section`.
If you want a section or page to not be listed, set the `toc_hide` flag in front matter:
```yaml
toc_hide: true
```
### The Main Menu
The site links in the top-right menu -- and also in the footer -- are built by page-lookups. This is to make sure that the page actually exists. So, if the `case-studies` section does not exist in a site (language), it will not be linked to.
## Page Bundles
In addition to standalone content pages (Markdown files), Hugo supports [Page Bundles](https://gohugo.io/content-management/page-bundles/).
One example is [Custom Hugo Shortcodes](/docs/home/contribute/includes/). It is a socalled `leaf bundle`. Everything below the directory with the `index.md` will be part of the bundle, with page-relative links, images can be processed etc.:
```bash
en/docs/home/contribute/includes
├── example1.md
├── example2.md
├── index.md
└── podtemplate.json
```
Another example used widely is the `includes` bundle. It has `headless: true` set in front matter, which means that it does not get its own URL. It is only used in other pages.
```bash
en/includes
├── default-storage-class-prereqs.md
├── federated-task-tutorial-prereqs.md
├── federation-content-moved.md
├── index.md
├── partner-script.js
├── partner-style.css
├── task-tutorial-prereqs.md
├── user-guide-content-moved.md
└── user-guide-migration-notice.md
```
Some important notes to the files in the bundles:
* For translated bundles, any missing non-content files will be inherited from languages above. This avoids duplication.
* All the files in a bundle are what Hugo calls `Resources` and you can provide metadata per language, such as parameters and title, even if it does not supports front matter (YAML files etc.). See [Page Resources Metadata](https://gohugo.io/content-management/page-resources/#page-resources-metadata).
* The value you get from `.RelPermalink` from a `Resource` is page-relative.
## Styles
The `SASS` source of the stylesheets for this site is stored below `src/sass` and can be built with `make sass` (note that Hugo will get `SASS` support soon, see https://github.com/gohugoio/hugo/issues/4243).
{{% /capture %}}
{{% capture whatsnext %}}
* [Custom Hugo shortcodes](/docs/contribute/style/hugo_shortcodes)
* [Style guide](/docs/contribute/style/style-guide)
{{% /capture %}}
content/en/docs/contribute/style/hugo_shortcodes.md/example1.md
+9
View File
@@ -0,0 +1,9 @@
---
title: Example #1
---
This is an **example** content file inside the **includes** leaf bundle.
{{< note >}}
**Note:** Included content files can also contain shortcodes.
{{< /note >}}
content/en/docs/contribute/style/hugo_shortcodes.md/example2.md
+7
View File
@@ -0,0 +1,7 @@
---
title: Example #1
---
This is another **example** content file inside the **includes** leaf bundle.
content/en/docs/contribute/style/hugo_shortcodes.md/index.md
+211
View File
@@ -0,0 +1,211 @@
---
approvers:
- chenopis
title: Custom Hugo Shortcodes
content_template: templates/concept
---
{{% capture overview %}}
This page explains the custom Hugo shortcodes that can be used in Kubernetes documentation markdown.
Read more about shortcodes in the [Hugo documentation](https://gohugo.io/content-management/shortcodes).
{{% /capture %}}
{{% capture body %}}
## Feature state
In a markdown page (.md file) on this site, you can add a shortcode to display version and state of the documented feature.
### Feature state demo
Below is a demo of the feature state snippet. Here it is used to display the feature as stable in Kubernetes version 1.10.
```
{{</* feature-state for_k8s_version="v1.10" state="stable" */>}}
```
Will render to:
{{< feature-state for_k8s_version="v1.10" state="stable" >}}
The valid values for `state` are:
* alpha
* beta
* deprecated
* stable
### Feature state code
Below is the template code for each available feature state.
The displayed Kubernetes version defaults to that of the page or the site. This can be changed by passing the <code>for_k8s_version</code> shortcode parameter.
````
{{</* feature-state for_k8s_version="v1.10" state="stable" */>}}
````
Renders to:
{{< feature-state for_k8s_version="v1.10" state="stable" >}}
#### Alpha feature
````
{{</* feature-state feature-state state="alpha" */>}}
````
Renders to:
{{< feature-state state="alpha" >}}
#### Beta feature
````
{{</* feature-state feature-state state="beta" */>}}
````
Renders to:
{{< feature-state state="beta" >}}
#### Stable feature
````
{{</* feature-state feature-state state="stable" */>}}
````
Renders to:
{{< feature-state state="stable" >}}
#### Deprecated feature
````
{{</* feature-state feature-state state="deprecated" */>}}
````
Renders to:
{{< feature-state state="deprecated" >}}
## Glossary
You can reference glossary terms with an inclusion that will automatically update and replace content with the relevant links from [our glossary](/docs/reference/glossary/). When the term is moused-over by someone
using the online documentation, the glossary entry will display a tooltip.
The raw data for glossary terms is stored at [https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary](https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary), with a content file for each glossary term.
### Glossary Demo
For example, the following include within the markdown will render to {{< glossary_tooltip text="cluster" term_id="cluster" >}} with a tooltip:
````liquid
{{</* glossary_tooltip text="cluster" term_id="cluster" */>}}
````
## Tabs
In a markdown page (`.md` file) on this site, you can add a tab set to display multiple flavors of a given solution.
The `tabs` shortcode takes these parameters:
* `name`: The name as shown on the tab.
* `codelang`: If you provide inner content to the `tab` shortcode, you can tell Hugo what code language to use for highlighting.
* `include`: The file to include in the tab. If the tab lives in a Hugo [leaf bundle](https://gohugo.io/content-management/page-bundles/#leaf-bundles), the file -- which can be any MIME type supported by Hugo -- will be looked up in the bundle itself. If not, the content page to include will be looked up relative to the current. Note that with the `include` you will not have any shortcode inner content and must use the self-closing syntax, e.g. {{</* tab name="Content File #1" include="example1" /*/>}}. Non-content files will be code-highlighted. The language to use will be taken from the filename if not provided in `codelang`.
* If your inner content is markdown, you must use `%`-delimiter to surorund the tab, e.g. `{{%/* tab name="Tab 1" %}}This is **markdown**{{% /tab */%}}`
* You can combine the variations mentioned above inside a tab set.
Below is a demo of the tabs shortcode.
{{< note >}}
The tab **name** in a `tabs` definition must be unique within a content page.
{{< /note >}}
### Tabs demo: Code highlighting
```go-text-template
{{</* tabs name="tab_with_code" >}}
{{{< tab name="Tab 1" codelang="bash" >}}
echo "This is tab 1."
{{< /tab >}}
{{< tab name="Tab 2" codelang="go" >}}
println "This is tab 2."
{{< /tab >}}}
{{< /tabs */>}}
```
Will be rendered as:
{{< tabs name="tab_with_code" >}}
{{< tab name="Tab 1" codelang="bash" >}}
echo "This is tab 1."
{{< /tab >}}
{{< tab name="Tab 2" codelang="go" >}}
println "This is tab 2."
{{< /tab >}}
{{< /tabs >}}
### Tabs demo: Inline Markdown and HTML
```go-html-template
{{</* tabs name="tab_with_md" >}}
{{% tab name="Markdown" %}}
This is **some markdown.**
{{< note >}}**Note:** It can even contain shortcodes.{{< /note >}}
{{% /tab %}}
{{< tab name="HTML" >}}
<div>
<h3>Plain HTML</h3>
<p>This is some <i>plain</i> HTML.</p>
</div>
{{< /tab >}}
{{< /tabs */>}}
```
Will be rendered as:
{{< tabs name="tab_with_md" >}}
{{% tab name="Markdown" %}}
This is **some markdown.**
{{< note >}}**Note:** It can even contain shortcodes.{{< /note >}}
{{% /tab %}}
{{< tab name="HTML" >}}
<div>
<h3>Plain HTML</h3>
<p>This is some <i>plain</i> HTML.</p>
</div>
{{< /tab >}}
{{< /tabs >}}
### Tabs demo: File include
```go-text-template
{{</* 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" />}}
{{< /tabs */>}}
```
Will be rendered as:
{{< 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" />}}
{{< /tabs >}}
{{% /capture %}}
{{% capture whatsnext %}}
* Learn about [Hugo](https://gohugo.io/).
* Learn about [writing a new topic](/docs/home/contribute/write-new-topic/).
* Learn about [using page templates](/docs/home/contribute/page-templates/).
* Learn about [staging your changes](/docs/home/contribute/stage-documentation-changes/)
* Learn about [creating a pull request](/docs/home/contribute/create-pull-request/).
{{% /capture %}}
content/en/docs/contribute/style/hugo_shortcodes.md/podtemplate.json
+22
View File
@@ -0,0 +1,22 @@
{
"apiVersion": "v1",
"kind": "PodTemplate",
"metadata": {
"name": "nginx"
},
"template": {
"metadata": {
"labels": {
"name": "nginx"
},
"generateName": "nginx-"
},
"spec": {
"containers": [{
"name": "nginx",
"image": "dockerfile/nginx",
"ports": [{"containerPort": 80}]
}]
}
}
}
content/en/docs/contribute/style/page-templates.md
+239
View File
@@ -0,0 +1,239 @@
---
title: Using Page Templates
content_template: templates/concept
weight: 30
---
{{% capture overview %}}
When contributing new topics, apply one of the following templates to them.
This standardizes the user experience of a given page.
The page templates are in the
[`_includes/templates`](https://git.k8s.io/website/_includes/templates)
directory of the [`kubernetes/website`](https://github.com/kubernetes/website)
repository.
{{< note >}}
**Note**: Every new topic needs to use a template. If you are unsure which
template to use for a new topic, start with the
[concept template](#concept-template).
{{< /note >}}
{{% /capture %}}
{{< toc >}}
{{% capture body %}}
## Concept template
A concept page explains some aspect of Kubernetes. For example, a concept
page might describe the Kubernetes Deployment object and explain the role it
plays as an application is deployed, scaled, and updated. Typically, concept
pages don't include sequences of steps, but instead provide links to tasks or
tutorials.
To write a new concept page, create a Markdown file in a subdirectory of the
`/content/en/docs/concepts` directory, with the following characteristics:
- In the page's YAML front-matter, set `content_template: templates/concept`.
- In the page's body, set the required `capture` variables and any optional
ones you want to include:
| Variable | Required? |
|===============|===========|
| overview | yes |
| body | yes |
| whatsnext | no |
The page's body will look like this (remove any optional captures you don't
need):
```
{% raw %}
{{% capture overview %}}
{{% /capture %}}
{{< toc >}}
{{% capture body %}}
{{% /capture %}}
{{% capture whatsnext %}}
{{% /capture %}}
{% endraw %}
```
- Within each section, write your content. Use the following guidelines:
- Use a minimum of H2 headings (with two leading `#` characters). The sections
themselves are titled automatically by the template.
- For `overview`, use a paragraph to set context for the entire topic.
- Add the `{{< toc >}}` shortcode to show an in-page table of contents.
- For `body`, explain the concept using free-form Markdown.
- For `whatsnext`, give a bullet list of up to 5 topics the reader might be
interested in reading next.
An example of a published topic that uses the concept template is
[Annotations](/docs/concepts/overview/working-with-objects/annotations/). The
page you are currently reading also uses the content template.
## Task template
A task page shows how to do a single thing, typically by giving a short
sequence of steps. Task pages have minimal explanation, but often provide links
to conceptual topics that provide related background and knowledge.
To write a new task page, create a Markdown file in a subdirectory of the
`/content/en/docs/tasks` directory, with the following characteristics:
- In the page's YAML front-matter, set `content_template: templates/task`.
- In the page's body, set the required `capture` variables and any optional
ones you want to include:
| Variable | Required? |
|===============|===========|
| overview | yes |
| prerequisites | yes |
| steps | no |
| discussion | no |
| whatsnext | no |
The page's body will look like this (remove any optional captures you don't
need):
```
{% raw %}
{{% capture overview %}}
{{% /capture %}}
{{< toc >}}
{{% capture prerequisites %}}
{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
{{% /capture %}}
{{% capture steps %}}
{{% /capture %}}
{{% capture discussion %}}
{{% /capture %}}
{{% capture whatsnext %}}
{{% /capture %}}
{% endraw %}
```
- Within each section, write your content. Use the following guidelines:
- Use a minimum of H2 headings (with two leading `#` characters). The sections
themselves are titled automatically by the template.
- For `overview`, use a paragraph to set context for the entire topic.
- Add the `{{< toc >}}` shortcode to show an in-page table of contents.
- For `prerequisites`, use bullet lists when possible. Add additional
prerequisites below the ones included by the `include` in the example
above. The default prerequisites include a running Kubernetes cluster.
- For `steps`, use numbered lists.
- For discussion, use normal content to expand upon the information covered
in `steps`.
- For `whatsnext`, give a bullet list of up to 5 topics the reader might be
interested in reading next.
An example of a published topic that uses the task template is [Using an HTTP proxy to access the Kubernetes API](/docs/tasks/access-kubernetes-api/http-proxy-access-api).
## Tutorial template
A tutorial page shows how to accomplish a goal that is larger than a single
task. Typically a tutorial page has several sections, each of which has a
sequence of steps. For example, a tutorial might provide a walkthrough of a
code sample that illustrates a certain feature of Kubernetes. Tutorials can
include surface-level explanations, but should link to related concept topics
for deep explanations.
To write a new tutorial page, create a Markdown file in a subdirectory of the
`/content/en/docs/tutorials` directory, with the following characteristics:
- In the page's YAML front-matter, set `content_template: templates/tutorial`.
- In the page's body, set the required `capture` variables and any optional
ones you want to include:
| Variable | Required? |
|===============|===========|
| overview | yes |
| prerequisites | yes |
| objectives | yes |
| lessoncontent | yes |
| cleanup | no |
| whatsnext | no |
The page's body will look like this (remove any optional captures you don't
need):
```
{% raw %}
{{% capture overview %}}
{{% /capture %}}
{{< toc >}}
{{% capture prerequisites %}}
{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
{{% /capture %}}
{{% capture objectives %}}
{{% /capture %}}
{{% capture lessoncontent %}}
{{% /capture %}}
{{% capture cleanup %}}
{{% /capture %}}
{{% capture whatsnext %}}
{{% /capture %}}
{% endraw %}
```
- Within each section, write your content. Use the following guidelines:
- Use a minimum of H2 headings (with two leading `#` characters). The sections
themselves are titled automatically by the template.
- For `overview`, use a paragraph to set context for the entire topic.
- Add the `{{< toc >}}` shortcode to show an in-page table of contents.
- For `prerequisites`, use bullet lists when possible. Add additional
prerequisites below the ones included by default.
- For `objectives`, use bullet lists.
- For `lessoncontent`, use a mix of numbered lists and narrative content as
appropriate.
- For `cleanup`, use numbered lists to describe the steps to clean up the
state of the cluster after finishing the task.
- For `whatsnext`, give a bullet list of up to 5 topics the reader might be
interested in reading next.
An example of a published topic that uses the tutorial template is
[Running a Stateless Application Using a Deployment](/docs/tutorials/stateless-application/run-stateless-application-deployment/).
{{% /capture %}}
{{% capture whatsnext %}}
- Learn about the [style guide](/docs/contribute/style/style-guide/)
- Learn about [content organization](/docs/contribute/style/content-organization/)
{{% /capture %}}
content/en/docs/contribute/style/style-guide.md
+394
View File
@@ -0,0 +1,394 @@
---
title: Documentation Style Guide
linktitle: Style guide
content_template: templates/concept
weight: 10
---
{{% capture overview %}}
This page gives writing style guidelines for the Kubernetes documentation.
These are guidelines, not rules. Use your best judgment, and feel free to
propose changes to this document in a pull request.
For additional information on creating new content for the Kubernetes
docs, follow the instructions on
[using page templates](/docs/contribute/style/page-templates/) and
[creating a documentation pull request](/docs/contribute/start/#improve-existing-content).
{{% /capture %}}
{{% capture 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,
and representing feature state.
{{< /note >}}
## Language
Kubernetes documentation uses US English.
## Documentation formatting standards
### Use camel case for API objects
When you refer to an API object, use the same uppercase and lowercase letters
that are used in the actual object name. Typically, the names of API
objects use
[camel case](https://en.wikipedia.org/wiki/Camel_case).
Don't split the API object name into separate words. For example, use
PodTemplateList, not Pod Template List.
Refer to API objects without saying "object," unless omitting "object"
leads to an awkward construction.
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>The Pod has two containers.</td><td>The pod has two containers.</td></tr>
<tr><td>The Deployment is responsible for ...</td><td>The Deployment object is responsible for ...</td></tr>
<tr><td>A PodList is a list of Pods.</td><td>A Pod List is a list of pods.</td></tr>
<tr><td>The two ContainerPorts ...</td><td>The two ContainerPort objects ...</td></tr>
<tr><td>The two ContainerStateTerminated objects ...</td><td>The two ContainerStateTerminateds ...</td></tr>
</table>
### Use angle brackets for placeholders
Use angle brackets for placeholders. Tell the reader what a placeholder
represents.
1. Display information about a pod:
kubectl describe pod <pod-name>
where `<pod-name>` is the name of one of your pods.
### Use bold for user interface elements
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>Click <b>Fork</b>.</td><td>Click "Fork".</td></tr>
<tr><td>Select <b>Other</b>.</td><td>Select 'Other'.</td></tr>
</table>
### Use italics to define or introduce new terms
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>A <i>cluster</i> is a set of nodes ...</td><td>A "cluster" is a set of nodes ...</td></tr>
<tr><td>These components form the <i>control plane.</i></td><td>These components form the <b>control plane.</b></td></tr>
</table>
### Use code style for filenames, directories, and paths
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>Open the <code>envars.yaml</code> file.</td><td>Open the envars.yaml file.</td></tr>
<tr><td>Go to the <code>/docs/tutorials</code> directory.</td><td>Go to the /docs/tutorials directory.</td></tr>
<tr><td>Open the <code>/_data/concepts.yaml</code><!--to-unbreak-atom-highlighting_--> file.</td><td>Open the /_data/concepts.yaml<!--to-unbreak-atom-highlighting_--> file.</td></tr>
</table>
### Use the international standard for punctuation inside quotes
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>events are recorded with an associated "stage".</td><td>events are recorded with an associated "stage."</td></tr>
<tr><td>The copy is called a "fork".</td><td>The copy is called a "fork."</td></tr>
</table>
## Inline code formatting
### Use code style for inline code and commands
For inline code in an HTML document, use the `<code>` tag. In a Markdown
document, use the backtick (`).
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>The <code>kubectl run</code> command creates a Deployment.</td><td>The "kubectl run" command creates a Deployment.</td></tr>
<tr><td>For declarative management, use <code>kubectl apply</code>.</td><td>For declarative management, use "kubectl apply".</td></tr>
</table>
### Use code style for object field names
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>Set the value of the <code>replicas</code> field in the configuration file.</td><td>Set the value of the "replicas" field in the configuration file.</td></tr>
<tr><td>The value of the <code>exec</code> field is an ExecAction object.</td><td>The value of the "exec" field is an ExecAction object.</td></tr>
</table>
### Use normal style for string and integer field values
For field values of type string or integer, use normal style without quotation marks.
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>Set the value of <code>imagePullPolicy</code> to Always.</td><td>Set the value of <code>imagePullPolicy</code> to "Always".</td></tr>
<tr><td>Set the value of <code>image</code> to nginx:1.8.</td><td>Set the value of <code>image</code> to <code>nginx:1.8</code>.</td></tr>
<tr><td>Set the value of the <code>replicas</code> field to 2.</td><td>Set the value of the <code>replicas</code> field to <code>2</code>.</td></tr>
</table>
## Code snippet formatting
### Don't include the command prompt
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>kubectl get pods</td><td>$ kubectl get pods</td></tr>
</table>
### Separate commands from output
Verify that the pod is running on your chosen node:
kubectl get pods --output=wide
The output is similar to this:
NAME READY STATUS RESTARTS AGE IP NODE
nginx 1/1 Running 0 13s 10.200.0.4 worker0
### Versioning Kubernetes examples
Code examples and configuration examples that include version information should be consistent with the accompanying text. Identify the Kubernetes version in the **Before you begin** section.
To specify the Kubernetes version for a task or tutorial page, include `min-kubernetes-server-version` in the front matter of the page.
If the example YAML is in a standalone file, find and review the topics that include it as a reference.
Verify that any topics using the standalone YAML have the appropriate version information defined.
If a stand-alone YAML file is not referenced from any topics, consider deleting it instead of updating it.
For example, if you are writing a tutorial that is relevant to Kubernetes version 1.8, the front-matter of your markdown file should look something like:
```yaml
---
title: <your tutorial title here>
min-kubernetes-server-version: v1.8
---
```
In code and configuration examples, do not include comments about alternative versions.
Be careful to not include incorrect statements in your examples as comments, such as:
```yaml
apiVersion: v1 # earlier versions use...
kind: Pod
...
```
## Kubernetes.io word list
A list of Kubernetes-specific terms and words to be used consistently across the site.
<table>
<tr><th>Term</th><th>Usage</th></tr>
<tr><td>Kubernetes</td><td>Kubernetes should always be capitalized.</td></tr>
<tr><td>Docker</td><td>Docker should always be capitalized.</td></tr>
<tr><td>SIG Docs</td><td>SIG Docs rather than SIG-DOCS or other variations.</td></tr>
</table>
## Shortcodes
Hugo [Shortcodes](https://gohugo.io/content-management/shortcodes) help create different rhetorical appeal levels. Our documentation supports three different shortcodes in this category: **Note:** {{</* note */>}}, **Caution:** {{</* caution */>}}, and **Warning:** {{</* warning */>}}.
1. Surround the text with an opening and closing shortcode.
2. Use the following syntax to apply a style:
```
{{</* note */>}}
**Note:** The prefix you use is the same text you use in the tag.
{{</* /note */>}}
```
The output is:
{{< note >}}
**Note:** The prefix you choose is the same text for the tag.
{{< /note >}}
### Note
Use {{</* note */>}} to highlight a tip or a piece of information that may be helpful to know.
For example:
```
{{</* note */>}}
**Note:** You can _still_ use Markdown inside these callouts.
{{</* /note */>}}
```
The output is:
{{< note >}}
**Note:** You can _still_ use Markdown inside these callouts.
{{< /note >}}
### Caution
Use {{</* caution */>}} to call attention to an important piece of information to avoid pitfalls.
For example:
```
{{</* caution */>}}
**Caution:** The callout style only applies to the line directly above the tag.
{{</* /caution */>}}
```
The output is:
{{< caution >}}
**Caution:** The callout style only applies to the line directly above the tag.
{{< /caution >}}
### Warning
Use {{</* warning */>}} to indicate danger or a piece of information that is crucial to follow.
For example:
```
{{</* warning */>}}
**Warning:** Beware.
{{</* /warning */>}}
```
The output is:
{{< warning >}}
**Warning:** Beware.
{{< /warning >}}
## Common Shortcode Issues
### Ordered Lists
Shortcodes will interrupt numbered lists unless you indent four spaces before the notice and the tag.
For example:
1. Preheat oven to 350˚F
1. Prepare the batter, and pour into springform pan.
{{</* note */>}}**Note:** Grease the pan for best results.{{</* /note */>}}
1. Bake for 20-25 minutes or until set.
The output is:
1. Preheat oven to 350˚F
1. Prepare the batter, and pour into springform pan.
{{< note >}}**Note:** Grease the pan for best results.{{< /note >}}
1. Bake for 20-25 minutes or until set.
## Content best practices
This section contains suggested best practices for clear, concise, and consistent content.
### Use present tense
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>This command starts a proxy.</td><td>This command will start a proxy.</td></tr>
</table>
Exception: Use future or past tense if it is required to convey the correct
meaning.
### Use active voice
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>You can explore the API using a browser.</td><td>The API can be explored using a browser.</td></tr>
<tr><td>The YAML file specifies the replica count.</td><td>The replica count is specified in the YAML file.</td></tr>
</table>
Exception: Use passive voice if active voice leads to an awkward construction.
### Use simple and direct language
Use simple and direct language. Avoid using unnecessary phrases, such as saying "please."
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>To create a ReplicaSet, ...</td><td>In order to create a ReplicaSet, ...</td></tr>
<tr><td>See the configuration file.</td><td>Please see the configuration file.</td></tr>
<tr><td>View the Pods.</td><td>With this next command, we'll view the Pods.</td></tr>
</table>
### Address the reader as "you"
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>You can create a Deployment by ...</td><td>We'll create a Deployment by ...</td></tr>
<tr><td>In the preceding output, you can see...</td><td>In the preceding output, we can see ...</td></tr>
</table>
### Avoid Latin phrases
Prefer English terms over Latin abbreviations.
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>For example, ...</td><td>e.g., ...</td></tr>
<tr><td>That is, ...</td><td>i.e., ...</td></tr>
</table>
Exception: Use "etc." for et cetera.
## Patterns to avoid
### Avoid using "we"
Using "we" in a sentence can be confusing, because the reader might not know
whether they're part of the "we" you're describing.
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>Version 1.4 includes ...</td><td>In version 1.4, we have added ...</td></tr>
<tr><td>Kubernetes provides a new feature for ...</td><td>We provide a new feature ...</td></tr>
<tr><td>This page teaches you how to use pods.</td><td>In this page, we are going to learn about pods.</td></tr>
</table>
### Avoid jargon and idioms
Some readers speak English as a second language. Avoid jargon and idioms to help them understand better.
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>Internally, ...</td><td>Under the hood, ...</td></tr>
<tr><td>Create a new cluster.</td><td>Turn up a new cluster.</td></tr>
</table>
### Avoid statements about the future
Avoid making promises or giving hints about the future. If you need to talk about
an alpha feature, put the text under a heading that identifies it as alpha
information.
### Avoid statements that will soon be out of date
Avoid words like "currently" and "new." A feature that is new today might not be
considered new in a few months.
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>In version 1.4, ...</td><td>In the current version, ...</td></tr>
<tr><td>The Federation feature provides ...</td><td>The new Federation feature provides ...</td></tr>
</table>
{{% /capture %}}
{{% capture whatsnext %}}
* Learn about [writing a new topic](/docs/home/contribute/write-new-topic/).
* Learn about [using page templates](/docs/home/contribute/page-templates/).
* Learn about [staging your changes](/docs/home/contribute/stage-documentation-changes/)
* Learn about [creating a pull request](/docs/home/contribute/create-pull-request/).
{{% /capture %}}
content/en/docs/contribute/style/write-new-topic.md
+181
View File
@@ -0,0 +1,181 @@
---
title: Writing a new topic
content_template: templates/task
weight: 20
---
{{% capture overview %}}
This page shows how to create a new topic for the Kubernetes docs.
{{% /capture %}}
{{% capture prerequisites %}}
Create a fork of the Kubernetes documentation repository as described in
[Start contributing](/docs/contribute/start/).
{{% /capture %}}
{{% capture steps %}}
## Choosing a page type
As you prepare to write a new topic, think about which of these page types
is the best fit for your content:
<table>
<tr>
<td>Concept</td>
<td>A concept page explains some aspect of Kubernetes. For example, a concept page might describe the Kubernetes Deployment object and explain the role it plays as an application is deployed, scaled, and updated. Typically, concept pages don't include sequences of steps, but instead provide links to tasks or tutorials. For an example of a concept topic, see <a href="/docs/concepts/architecture/nodes/">Nodes</a>.</td>
</tr>
<tr>
<td>Task</td>
<td>A task page shows how to do a single thing. The idea is to give readers a sequence of steps that they can actually do as they read the page. A task page can be short or long, provided it stays focused on one area. In a task page, it is OK to blend brief explanations with the steps to be performed, but if you need to provide a lengthy explanation, you should do that in a concept topic. Related task and concept topics should link to each other. For an example of a short task page, see <a href="/docs/tasks/configure-pod-container/configure-volume-storage/">Configure a Pod to Use a Volume for Storage</a>. For an example of a longer task page, see <a href="/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/">Configure Liveness and Readiness Probes</a></td>
</tr>
<tr>
<td>Tutorial</td>
<td>A tutorial page shows how to accomplish a goal that ties together several Kubernetes features. A tutorial might provide several sequences of steps that readers can actually do as they read the page. Or it might provide explanations of related pieces of code. For example, a tutorial could provide a walkthrough of a code sample. A tutorial can include brief explanations of the Kubernetes features that are being tied together, but should link to related concept topics for deep explanations of individual features.</td>
</tr>
</table>
Use a template for each new page. Each page type has a
[template](/docs/contribute/style/page-templates/)
that you can use as you write your topic. Using templates helps ensure
consistency among topics of a given type.
## Choosing a title and filename
Choose a title that has the keywords you want search engines to find.
Create a filename that uses the words in your title separated by hyphens.
For example, the topic with title
[Using an HTTP Proxy to Access the Kubernetes API](/docs/tasks/access-kubernetes-api/http-proxy-access-api/)
has filename `http-proxy-access-api.md`. You don't need to put
"kubernetes" in the filename, because "kubernetes" is already in the
URL for the topic, for example:
http://kubernetes.io/docs/tasks/access-kubernetes-api/http-proxy-access-api/
## Adding the topic title to the front matter
In your topic, put a `title` field in the
[front matter](https://jekyllrb.com/docs/frontmatter/).
The front matter is the YAML block that is between the
triple-dashed lines at the top of the page. Here's an example:
---
title: Using an HTTP Proxy to Access the Kubernetes API
---
## Choosing a directory
Depending on your page type, put your new file in a subdirectory of one of these:
* /content/en/docs/tasks/
* /content/en/docs/tutorials/
* /content/en/docs/concepts/
You can put your file in an existing subdirectory, or you can create a new
subdirectory.
## Placing your topic in the table of contents
The table of contents is built dynamicaly using the directory structure of the
documentation source. The top-level directories under `/content/en/docs/` create
top-level navigation, and subdirectories each have entries in the table of
contents.
Each subdirectory has a file `_index.md`, which represents the "home" page for
a given subdirectory's content. The `_index.md` does not need a template. It
can contain overview content about the topics in the subdirectory.
Other files in a directory are sorted alphabetically by default. This is almost
never the best order. To control the relative sorting of topics in a
subdirectory, set the `weight:` front-matter key to an integer. Typically, we
use multiples of 10, to account for adding topics later. For instance, a topic
with weight `10` will come before one with weight `20`.
## Embedding code in your topic
If you want to include some code in your topic, you can embed the code in your
file directly using the markdown code block syntax. This is recommended for the
following cases (not an exhaustive list):
- The code shows the output from a command such as
`kubectl get deploy mydeployment -o json | jq '.status'`.
- The code is not generic enough for users to try out. As an example, you can
embed the YAML
file for creating a Pod which depends on a specific
[FlexVolume](/docs/concepts/storage/volumes#flexvolume) implementation.
- The code is an incomplete example because its purpose is to highlight a
portion of a larger file. For example, when describing ways to
customize the [PodSecurityPolicy](/docs/tasks/administer-cluster/sysctl-cluster/#podsecuritypolicy)
for some reasons, you can provide a short snippet directly in your topic file.
- The code is not meant for users to try out due to other reasons. For example,
when describing how a new attribute should be added to a resource using the
`kubectl edit` command, you can provide a short example that includes only
the attribute to add.
## Including code from another file
Another way to include code in your topic is to create a new, complete sample
file (or group of sample files) and then reference the sample from your topic.
Use this method to include sample YAML files when the sample is generic and
reusable, and you want the reader to try it out themselves.
When adding a new standalone sample file, such as a YAML file, place the code in
one of the `<LANG>/examples/` subdirectories where `<LANG>` is the language for
the topic. In your topic file, use the `codenew` shortcode:
<pre>&#123;&#123;&lt; codenew file="&lt;RELPATH&gt;/my-example-yaml&gt;" &gt;&#125;&#125;</pre>
where `<RELPATH>` is the path to the file to include, relative to the
`examples` directory. The following Hugo shortcode references a YAML
file located at `/content/en/examples/pods/storage/gce-volume.yaml`.
```none
{{</* codenew file="pods/storage/gce-volume.yaml" */>}}
```
{{< note >}}
**Note**: To show raw Hugo shortcodes as in the above example and prevent Hugo
from interpreting them, use C-style comments directly after the `<` and before
the `>` characters. View the code for this page for an example.
{{< /note >}}
## Showing how to create an API object from a configuration file
If you need to demonstrate how to create an API object based on a
configuration file, place the configuration file in one of the subdirectories
under `<LANG>/examples`.
In your topic, show this command:
```
kubectl create -f https://k8s.io/examples/pods/storage/gce-volume.yaml
```
{{< note >}}
**Note**: When adding new YAML files to the `<LANG>/examples` directory, make
sure the file is also included into the `<LANG>/examples_test.go` file. The
Travis CI for the Website automatically runs this test case when PRs are
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/).
## Adding images to a topic
Put image files in the `/images` directory. The preferred
image format is SVG.
{{% /capture %}}
{{% capture whatsnext %}}
* Learn about [using page templates](/docs/home/contribute/page-templates/).
* Learn about [staging your changes](/docs/home/contribute/stage-documentation-changes/).
* Learn about [creating a pull request](/docs/home/contribute/create-pull-request/).
{{% /capture %}}