Modernize upstream reference docs contribution guide #56441
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -6,78 +6,88 @@ weight: 20 | |||||
|
|
||||||
| <!-- overview --> | ||||||
|
|
||||||
| This page shows how to contribute documentation fixes to the upstream | ||||||
| `kubernetes/kubernetes` project. You can fix bugs found in the Kubernetes API | ||||||
| reference or in the reference pages for Kubernetes components such as `kubeadm`, | ||||||
| `kube-apiserver`, and `kube-controller-manager`. | ||||||
|
|
||||||
| If you instead want to regenerate the reference documentation from the | ||||||
| upstream code, see the following instructions: | ||||||
|
|
||||||
| - [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/) | ||||||
| - [Generating Reference Documentation for the Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/) | ||||||
|
|
||||||
| ## {{% heading "prerequisites" %}} | ||||||
|
|
||||||
| - You need a machine that is running Linux or macOS. | ||||||
|
|
||||||
| - You need to have these tools installed: | ||||||
|
|
||||||
| - [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) | ||||||
| - [Go](https://go.dev/doc/install), using the version required by the | ||||||
| repository you are building | ||||||
| - [make](https://www.gnu.org/software/make/) | ||||||
| - [gcc compiler/linker](https://gcc.gnu.org/) | ||||||
| - [Docker](https://docs.docker.com/engine/installation/), if you need to run | ||||||
| Docker-based build or preview targets | ||||||
|
|
||||||
| - Your `PATH` environment variable must include the required build tools, such | ||||||
| as the `go` binary. | ||||||
|
|
||||||
| - 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 [Open a pull request](/docs/contribute/new-content/open-a-pr/). | ||||||
|
|
||||||
| You do not need to set `GOPATH` or use `go get` to clone Kubernetes repositories. | ||||||
| Clone the repositories with `git`. | ||||||
|
|
||||||
| <!-- steps --> | ||||||
|
|
||||||
| ## The big picture | ||||||
|
|
||||||
| The reference documentation for the Kubernetes API and the `kube-*` components, | ||||||
| such as `kube-apiserver` and `kube-controller-manager`, is generated from source | ||||||
| code in the [upstream Kubernetes](https://github.com/kubernetes/kubernetes/) | ||||||
| repository. | ||||||
|
|
||||||
| When you see bugs in generated reference documentation, consider fixing the | ||||||
| authoritative comments or generated inputs in the upstream project. After the | ||||||
| upstream change is merged, regenerate the published reference documentation in | ||||||
| the `kubernetes/website` repository. | ||||||
|
|
||||||
| ## Set up the local repositories | ||||||
|
|
||||||
| Create a workspace and clone the repositories you need: | ||||||
|
|
||||||
| ```shell | ||||||
| mkdir -p ~/src/k8s.io | ||||||
| cd ~/src/k8s.io | ||||||
|
|
||||||
| git clone https://github.com/kubernetes/kubernetes.git | ||||||
| git clone https://github.com/kubernetes-sigs/reference-docs.git | ||||||
| git clone https://github.com/<your-username>/website.git | ||||||
| ``` | ||||||
|
|
||||||
| You use the `kubernetes/kubernetes` clone to fix the upstream source comments | ||||||
| and regenerate upstream generated files. You use the `reference-docs` and | ||||||
| `website` clones later to verify and publish the reference documentation. | ||||||
|
|
||||||
| The remaining steps refer to these local paths: | ||||||
|
|
||||||
| - `<k8s-base>`: your `kubernetes/kubernetes` clone | ||||||
| - `<rdocs-base>`: your `kubernetes-sigs/reference-docs` clone | ||||||
| - `<web-base>`: your `kubernetes/website` fork clone | ||||||
|
|
||||||
|
Comment on lines
+58
to
80
Contributor
There was a problem hiding this comment. This page should be focused on fixing content in kubernetes/kubernetes and opening a PR there; the regenerate/publish step already exist in Generating Reference Documentation for the Kubernetes API, which covers cloning reference-docs/website. Could we keep this page k/k-focused and drop the extra clones + / here, to avoid duplicating that guide? This is one of the improvements we want to make |
||||||
| ## Edit the Kubernetes source code | ||||||
|
|
||||||
| The Kubernetes API reference documentation is generated from an OpenAPI spec, | ||||||
| which is generated from the Kubernetes source code. If you want to change the | ||||||
| API reference documentation, the first step is to change one or more comments in | ||||||
| the Kubernetes source code. | ||||||
|
|
||||||
| The documentation for the `kube-*` components is also generated from upstream | ||||||
| source code. You must change the code related to the component you want to fix | ||||||
| in order to fix the generated documentation. | ||||||
|
|
||||||
| ### Make changes to the upstream source code | ||||||
|
|
||||||
|
|
@@ -88,7 +98,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 default branch | ||||||
| and make sure it is up to date: | ||||||
|
|
||||||
| ```shell | ||||||
|
|
@@ -97,31 +107,32 @@ git checkout master | |||||
| git pull https://github.com/kubernetes/kubernetes master | ||||||
| ``` | ||||||
|
|
||||||
| Suppose this source file in that default branch has the typo `atmost`: | ||||||
|
Contributor
There was a problem hiding this comment. the existing quote is the correct thing here as per style guide and not your changes to backtick |
||||||
|
|
||||||
| [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: | ||||||
|
|
||||||
| ```none | ||||||
| On branch master | ||||||
| ... | ||||||
| modified: staging/src/k8s.io/api/apps/v1/types.go | ||||||
| ``` | ||||||
|
|
||||||
| ### Commit 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 source | ||||||
| changes and generated changes separated into two commits. | ||||||
|
|
||||||
| ### Generate the OpenAPI spec and related files | ||||||
|
|
||||||
|
|
@@ -134,7 +145,7 @@ Go to `<k8s-base>` and run these scripts: | |||||
|
|
||||||
| Run `git status` to see what was generated. | ||||||
|
|
||||||
| ```none | ||||||
| On branch master | ||||||
| ... | ||||||
| modified: api/openapi-spec/swagger.json | ||||||
|
|
@@ -144,18 +155,22 @@ On branch master | |||||
| 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: | ||||||
|
|
||||||
| ```shell | ||||||
| git diff -a api/openapi-spec/swagger.json | ||||||
| ``` | ||||||
|
|
||||||
| This is important because `swagger.json` is the input to the next stage of the | ||||||
| reference documentation generation process. | ||||||
|
|
||||||
| Run `git add` and `git commit` to commit your generated changes. Now you have two | ||||||
| commits: one that contains the edited `types.go` file, and one that contains the | ||||||
| generated OpenAPI spec and related files. Keep these two commits separate. Do not | ||||||
| squash your commits. | ||||||
|
|
||||||
| Submit your changes as a pull request to the `master` branch of the | ||||||
|
Contributor
There was a problem hiding this comment. you did not need to add backtick to branches |
||||||
| [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 is merged. | ||||||
|
|
@@ -164,64 +179,69 @@ to monitor your pull request until it is merged. | |||||
| is an example of a pull request that fixes a typo in the Kubernetes source code. | ||||||
|
|
||||||
| {{< note >}} | ||||||
| It can be tricky to determine the correct source file to change. In the | ||||||
| preceding example, the authoritative source file is in the `staging` directory | ||||||
| in the `kubernetes/kubernetes` repository. In your situation, the `staging` | ||||||
| directory might not be the authoritative source. For guidance, check the | ||||||
| `README` files in the | ||||||
| [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes/tree/master/staging) | ||||||
| repository and in related repositories, such as | ||||||
| [kubernetes/apiserver](https://github.com/kubernetes/apiserver/blob/master/README.md). | ||||||
| {{< /note >}} | ||||||
|
|
||||||
| ### Cherry pick your commit into a release branch | ||||||
|
Contributor
There was a problem hiding this comment. if this is followed https://github.com/kubernetes/website/pull/56441/changes#r3566372837, then you could update this to
Suggested change
|
||||||
|
|
||||||
| In the preceding section, you edited a file in the `master` branch, ran scripts | ||||||
| to generate an OpenAPI spec and related files, and 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 | ||||||
| {{< 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-{{< 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 >}} | ||||||
| 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 need to | ||||||
| work with someone who can set the label and milestone for you. | ||||||
| {{< /note >}} | ||||||
|
|
||||||
| When you have a pull request in place for cherry picking your one commit into | ||||||
| the release-{{< skew prevMinorVersion >}} branch, run these scripts in the | ||||||
| release-{{< skew prevMinorVersion >}} branch of your local environment: | ||||||
|
|
||||||
| ```shell | ||||||
| ./hack/update-codegen.sh | ||||||
| ./hack/update-openapi-spec.sh | ||||||
| ``` | ||||||
|
|
||||||
| 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-{{< skew prevMinorVersion >}} branch. | ||||||
|
|
||||||
| 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`. | ||||||
| The 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 | ||||||
| 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 Kubernetes | ||||||
| {{< skew latestVersion >}}. | ||||||
|
|
||||||
|
Comment on lines
192
to
238
Contributor
There was a problem hiding this comment. I suggest, trimming this whole section to just a few lines and since this section is optional, it looks unnecessary large if we already have a community documentation |
||||||
| ## Generate 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. The `swagger.json` file is the OpenAPI | ||||||
| definition file to use for generating the API reference documentation. | ||||||
|
|
||||||
| You are now ready to follow the | ||||||
| [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/) | ||||||
|
|
||||||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Since we have an updated prerequisites page from PR #56403, we should used that instead