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

Merge pull request #28461 from sftim/20210617_improve_make_generate_ref_docs 

Improve docs about contributing upstream for generated content
This commit is contained in:
Kubernetes Prow Robot 2021-08-10 00:15:19 -07:00 committed by GitHub
parent a80328f582 191c2bf4ee
commit 67eca4178c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 30 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
content/en/docs/contribute/generate-ref-docs/contribute-upstream.md
View File

@ -91,7 +91,7 @@ will be different in your situation.
Here's an example of editing a comment in the Kubernetes source code.
In your local kubernetes/kubernetes repository, check out the master branch,
In your local kubernetes/kubernetes repository, check out the default branch,
and make sure it is up to date:
```shell
@ -100,7 +100,7 @@ git checkout master
git pull https://github.com/kubernetes/kubernetes master
```
Suppose this source file in the master branch has the typo "atmost":
Suppose this source file in that default 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)
@ -183,12 +183,13 @@ In the preceding section, you edited a file in the master branch and then ran sc
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.
Kubernetes version {{< skew latestVersion >}}, and you want to backport your change into the
release-{{< skew prevMinorVersion >}} 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
commit into the release-{{< skew prevMinorVersion >}} 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://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md).
{{< note >}}
@ -197,8 +198,9 @@ pull request. If you don't have those permissions, you will need to work with so
and milestone for you.
{{< /note >}}
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.
When you have a pull request in place for cherry picking your one commit into the
release-{{< skew prevMinorVersion >}} branch, the next step is to run these scripts in the
release-{{< skew prevMinorVersion >}} branch of your local environment.
```shell
hack/update-generated-swagger-docs.sh
@ -208,14 +210,15 @@ 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.
and related files. Monitor your pull request until it gets merged into the
release-{{< skew prevMinorVersion >}} branch.
At this point, both the master branch and the release-1.9 branch have your updated `types.go`
At this point, both the master branch and the release-{{< skew prevMinorVersion >}} 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.
generated OpenAPI spec and other generated files in the release-{{< skew prevMinorVersion >}} branch are not necessarily
the same as the generated files in the master branch. The generated files in the release-{{< skew prevMinorVersion >}} branch
contain API elements only from Kubernetes {{< skew prevMinorVersion >}}. The generated files in the master branch might contain
API elements that are not in {{< skew prevMinorVersion >}}, but are under development for {{< skew latestVersion >}}.
## Generating the published reference docs

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

@ -86,12 +86,12 @@ The remaining steps refer to your base directory as `<rdocs-base>`.
In your local k8s.io/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.17, you could use these commands:
Kubernetes {{< skew prevMinorVersion >}}.0, you could use these commands:
```shell
cd <k8s-base>
git checkout v1.17.0
git pull https://github.com/kubernetes/kubernetes v1.17.0
git checkout v{{< skew prevMinorVersion >}}.0
git pull https://github.com/kubernetes/kubernetes {{< skew prevMinorVersion >}}.0
```
If you do not need to edit the `kubectl` source code, follow the instructions for
@ -109,7 +109,7 @@ local kubernetes/kubernetes repository, and then submit a pull request to the ma
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.
pull request until it is merged into the target branch of the kubernetes/kubernetes repository.
## Cherry picking your change into a release branch
@ -118,9 +118,10 @@ Kubernetes release. If you want your change to appear in the docs for a Kubernet
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.15 branch. For instructions
on how to do this, see
For example, suppose the master branch is being used to develop Kubernetes
{{< skew currentVersion >}}
and you want to backport your change to the release-{{< skew prevMinorVersion >}} branch. For
instructions on how to do this, see
[Propose a Cherry Pick](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md).
Monitor your cherry-pick pull request until it is merged into the release branch.
@ -138,14 +139,14 @@ Go to `<rdocs-base>`. On you command line, set the following environment variabl
* Set `K8S_ROOT` to `<k8s-base>`.
* Set `K8S_WEBROOT` to `<web-base>`.
* Set `K8S_RELEASE` to the version of the docs you want to build.
For example, if you want to build docs for Kubernetes 1.17, set `K8S_RELEASE` to 1.17.
For example, if you want to build docs for Kubernetes {{< skew prevMinorVersion >}}, set `K8S_RELEASE` to {{< skew prevMinorVersion >}}.
For example:
```shell
export K8S_WEBROOT=$GOPATH/src/github.com/<your-username>/website
export K8S_ROOT=$GOPATH/src/k8s.io/kubernetes
export K8S_RELEASE=1.17
export K8S_RELEASE={{< skew prevMinorVersion >}}
```
## Creating a versioned directory
@ -165,13 +166,14 @@ make createversiondirs
In your local `<k8s-base>` 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.17, checkout the `v1.17.0` tag. Make sure
to generate docs for Kubernetes {{< skew prevMinorVersion >}}.0, check out the
`v{{< skew prevMinorVersion >}}` tag. Make sure
you local branch is up to date.
```shell
cd <k8s-base>
git checkout v1.17.0
git pull https://github.com/kubernetes/kubernetes v1.17.0
git checkout v{{< skew prevMinorVersion >}}.0
git pull https://github.com/kubernetes/kubernetes v{{< skew prevMinorVersion >}}.0
```
## Running the doc generation code