Skip to content

Commit

Permalink
Pick example versions based on current release
Browse files Browse the repository at this point in the history
  • Loading branch information
sftim committed Aug 4, 2021
1 parent 1421770 commit 191c2bf
Show file tree
Hide file tree
Showing 2 changed files with 28 additions and 23 deletions.
25 changes: 14 additions & 11 deletions content/en/docs/contribute/generate-ref-docs/contribute-upstream.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 >}}
Expand All @@ -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
Expand All @@ -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

Expand Down
26 changes: 14 additions & 12 deletions content/en/docs/contribute/generate-ref-docs/kubectl.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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
Expand Down

0 comments on commit 191c2bf

Please sign in to comment.