diff --git a/content/en/docs/contribute/generate-ref-docs/contribute-upstream.md b/content/en/docs/contribute/generate-ref-docs/contribute-upstream.md new file mode 100644 index 0000000000..14da3f5abe --- /dev/null +++ b/content/en/docs/contribute/generate-ref-docs/contribute-upstream.md @@ -0,0 +1,246 @@ +--- +title: Contributing to the Upstream Kubernetes Code +content_template: templates/task +--- + +{{% capture overview %}} + +This page shows how to contribute to the upstream kubernetes/kubernetes project +to fix bugs found in the Kubernetes API documentation or the `kube-*` +components such as `kube-apiserver`, `kube-controller-manager`, etc. + +If you instead want to regenerate the reference documentation for the Kubernetes +API or the `kube-*` components 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/) + +{{% /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 Pull Request](https://help.github.com/articles/creating-a-pull-request/) and +[GitHub Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962). + +{{% /capture %}} + + +{{% capture steps %}} + +## The big picture + +The reference documentation for the Kubernetes API and the `kube-*` components +such as `kube-apiserver`, `kube-controller-manager` are automatically generated +from the source code in the [upstream Kubernetes](https://github.com/kubernetes/kubernetes/). + +When you see bugs in the generated documentation, you may want to consider +creating a patch to fix it in the upstream project. + +## Cloning the Kubernetes repository + +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 ``. + +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 ``. + +## 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 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 the upstream +source code. You must change the code related to the component +you want to fix in order to fix the generated documentation. + +### Making changes to the upstream source code + +{{< 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 +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 `` and run these scripts: + +```shell +hack/update-generated-swagger-docs.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` is 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 contains the edited `types.go` file, and one that contains 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 is 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 >}} +It can be tricky to determine the correct source file to be changed. In the +preceding example, the authoritative source file is in 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, such as +[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. +{{< /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. + +```shell +hack/update-generated-swagger-docs.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. +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/) guide to to generate the +[published Kubernetes API reference documentation](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/). + +{{% /capture %}} + +{{% capture whatsnext %}} + +* [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/) +* [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 %}} + diff --git a/content/en/docs/contribute/generate-ref-docs/kubernetes-api.md b/content/en/docs/contribute/generate-ref-docs/kubernetes-api.md index 7dc9e813bd..b594ea9dd4 100644 --- a/content/en/docs/contribute/generate-ref-docs/kubernetes-api.md +++ b/content/en/docs/contribute/generate-ref-docs/kubernetes-api.md @@ -5,7 +5,7 @@ content_template: templates/task {{% capture overview %}} -This page shows how to update the automatically generated reference docs for the +This page shows how to update the generated reference docs for the Kubernetes API. {{% /capture %}} @@ -17,16 +17,13 @@ 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. +Your $GOPATH environment variable must be set. -You need to know how to create a pull request to a GitHub repository. +You need to know how to create a pull request (PR) 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 +[Creating a Documentation Pull Request](/docs/contribute/start/) and [GitHub Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962). {{% /capture %}} @@ -36,7 +33,7 @@ information, see ## The big picture -Updating the Kubernetes API reference documentation is a two-stage process: +The reference documentation for the Kubernetes API is generated in two separate stages: 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). @@ -44,6 +41,12 @@ this stage are at [kubernetes/kubernetes/hack](https://github.com/kubernetes/kub 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). +If you find bugs in the generated documentation generated, you need to +[fix them upstream](/docs/contribute/generate-ref-docs/contribute-upstream/). + +If you need only to regenerate the reference documentation from the OpenAPI +spec, continue reading this page. + ## Getting three repositories If you don't already have the kubernetes/kubernetes repository, get it now: @@ -88,154 +91,7 @@ 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 ``. -## 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 >}} -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 -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 `` 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 >}} -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. -{{< /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. - -```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 +## Generating the API reference docs for publishing The preceding section showed how to edit a source file and then generate several files, including `api/openapi-spec/swagger.json` in the @@ -276,35 +132,9 @@ The output shows that the file was copied: cp ~/src/github.com/kubernetes/kubernetes/api/openapi-spec/swagger.json gen-apidocs/generators/openapi-spec/swagger.json ``` -### Building the brodocs image +### Building the API reference docs -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: +Run the following command to generate the API reference docs: ```shell cd @@ -320,10 +150,9 @@ These two files are the output of a successful build. Verify that they exist: ## 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. +The preceding sections showed how to generate reference documentation for publication. -This section show how to copy the generated docs to the +This section shows how to copy the generated reference 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 @@ -336,7 +165,7 @@ your local kubernetes/website repository: make copyapi ``` -Go to the base of your local kubernetes/kubernetes repository, and +Go to the base of your local kubernetes/website repository, and see which files have been modified: ```shell @@ -359,7 +188,7 @@ from the `navData.js` that was already in the kubernetes/website` repository. In `` 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 +[pull request](/docs/contribute/start/) 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. @@ -377,5 +206,3 @@ in the [published reference documentation](/docs/reference/generated/kubernetes- {{% /capture %}} - - diff --git a/content/en/docs/contribute/generate-ref-docs/kubernetes-components.md b/content/en/docs/contribute/generate-ref-docs/kubernetes-components.md index cca0381185..adbd58eb7c 100644 --- a/content/en/docs/contribute/generate-ref-docs/kubernetes-components.md +++ b/content/en/docs/contribute/generate-ref-docs/kubernetes-components.md @@ -19,19 +19,15 @@ reference documentation for tools and components in the * 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/). +information, see [Creating a Documentation Pull Request](/docs/contribute/start/). {{% /capture %}} @@ -68,49 +64,16 @@ 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 ``. +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, +please follow [this guide](/docs/contribute/gen-ref-docs/contribute-upstream). + {{< 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 >}} -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 is located in the `kubernetes/website/update-imported-docs/` @@ -125,8 +88,7 @@ directory. The tool performs the following steps: repository under locations specified in the configuration file. When the Markdown files are in your local clone of the `kubernetes/website` -repository, you can submit them in a -[pull request](/docs/home/contribute/create-pull-request/) +repository, you can submit them in a [pull request](/docs/contribute/start/) to `kubernetes/website`. ## Customizing the config file @@ -237,5 +199,5 @@ topics will be visible in the * [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 %}} \ No newline at end of file +* [Contributing to the Upstream Kubernetes Project for Documentation](/docs/contribute/gen-ref-docs/contribute-upstream) +{{% /capture %}}