From 142177068b7598ff53e49e80ec655cf506f48e87 Mon Sep 17 00:00:00 2001 From: Tim Bannister Date: Thu, 17 Jun 2021 18:31:58 +0100 Subject: [PATCH 1/2] =?UTF-8?q?Refer=20to=20the=20=E2=80=9Cdefault?= =?UTF-8?q?=E2=80=9D=20rather=20than=20=E2=80=9Cmaster=E2=80=9D=20branch?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Get ready for a switch to "main" --- .../docs/contribute/generate-ref-docs/contribute-upstream.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/contribute/generate-ref-docs/contribute-upstream.md b/content/en/docs/contribute/generate-ref-docs/contribute-upstream.md index 656f8c971b..80b14aa87a 100644 --- a/content/en/docs/contribute/generate-ref-docs/contribute-upstream.md +++ b/content/en/docs/contribute/generate-ref-docs/contribute-upstream.md @@ -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) From 191c2bf4ee1572ca0be7a7dfdb8c2efd39ce2d8a Mon Sep 17 00:00:00 2001 From: Tim Bannister Date: Thu, 17 Jun 2021 18:33:43 +0100 Subject: [PATCH 2/2] Pick example versions based on current release --- .../generate-ref-docs/contribute-upstream.md | 25 ++++++++++-------- .../contribute/generate-ref-docs/kubectl.md | 26 ++++++++++--------- 2 files changed, 28 insertions(+), 23 deletions(-) diff --git a/content/en/docs/contribute/generate-ref-docs/contribute-upstream.md b/content/en/docs/contribute/generate-ref-docs/contribute-upstream.md index 80b14aa87a..4abf2de68b 100644 --- a/content/en/docs/contribute/generate-ref-docs/contribute-upstream.md +++ b/content/en/docs/contribute/generate-ref-docs/contribute-upstream.md @@ -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 diff --git a/content/en/docs/contribute/generate-ref-docs/kubectl.md b/content/en/docs/contribute/generate-ref-docs/kubectl.md index b216a0a5b7..a41c8d0df3 100644 --- a/content/en/docs/contribute/generate-ref-docs/kubectl.md +++ b/content/en/docs/contribute/generate-ref-docs/kubectl.md @@ -86,12 +86,12 @@ The remaining steps refer to your base directory as ``. 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 -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 ``. On you command line, set the following environment variabl * Set `K8S_ROOT` to ``. * Set `K8S_WEBROOT` to ``. * 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//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 `` 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 -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