# Contributing to the Upstream Kubernetes Code

Contributing to the Upstream Kubernetes CodeThis page shows how to contribute to the upstream kubernetes/kubernetes project. You can fix bugs found in the Kubernetes API documentation or the content of the Kubernetes components such as kubeadm, kube-apiserver, and kube-controller-manager.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 APIGenerating Reference Documentation for the Kubernetes Components and ToolsBefore you beginYou need to have these tools installed:GitGolang version 1.13+Dockeretcdmakegcc compiler/linkerYour 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 and GitHub Standard Fork & Pull Request Workflow.The big pictureThe 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.When you see bugs in the generated documentation, you may want to consider creating a patch to fix it in the upstream project.Clone the Kubernetes repositoryIf you don't already have the kubernetes/kubernetes repository, get it now:mkdir $GOPATH/src cd $GOPATH/src go get github.com/kubernetes/kubernetes Determine the base directory of your clone of the 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>.Determine the base directory of your clone of the kubernetes-sigs/reference-docs repository. For example, if you followed the preceding step to get the repository, your base directory is $GOPATH/src/github.com/kubernetes-sigs/reference-docs. The remaining steps refer to your base directory as <rdocs-base>.Edit the Kubernetes source codeThe 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.Make changes to the upstream source codeNote:The following steps are an example, not a general procedure. Details 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:cd <k8s-base> git checkout master git pull https://github.com/kubernetes/kubernetes master Suppose this source file in that default branch has the typo "atmost":kubernetes/kubernetes/staging/src/k8s.io/api/apps/v1/types.goIn your local environment, open types.go, and change "atmost" to "at most".Verify that you have changed the file:git status The output shows that you are on the master branch, and that the types.go source file has been modified:On branch master ... modified: staging/src/k8s.io/api/apps/v1/types.go Commit your edited fileRun 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.Generate the OpenAPI spec and related filesGo to <k8s-base> and run these scripts:./hack/update-codegen.sh ./hack/update-openapi-spec.sh Run git status to see what was generated.On branch master ... modified: api/openapi-spec/swagger.json modified: api/openapi-spec/v3/apis__apps__v1_openapi.json modified: pkg/generated/openapi/zz_generated.openapi.go modified: staging/src/k8s.io/api/apps/v1/generated.proto 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 to the master branch of the 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 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 repository and in related repositories, such as kubernetes/apiserver.Cherry pick your commit into a release branchIn 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.34, and you want to backport your change into the release-1.33 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.33 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.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.33 branch, the next step is to run these scripts in the release-1.33 branch of your local environment../hack/update-codegen.sh ./hack/update-openapi-spec.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.33 branch.At this point, both the master branch and the release-1.33 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.33 branch are not necessarily the same as the generated files in the master branch. The generated files in the release-1.33 branch contain API elements only from Kubernetes 1.33. The generated files in the master branch might contain API elements that are not in 1.33, but are under development for 1.34.Generate the published reference docsThe 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 guide to generate the published Kubernetes API reference documentation.What's nextGenerating Reference Documentation for the Kubernetes APIGenerating Reference Docs for Kubernetes Components and ToolsGenerating Reference Documentation for kubectl Commands