This document describes how to perform a semver release of one of the several Go modules in this repository.
In this repo, releasing a module is accomplished by applying a tag to the repo and pushing it upstream. A minor release branch is also created as necessary to track patch releases.
A properly formatted tag (described below) contains the module name and version.
Pushing the tag upstream will trigger Google Cloud Build to build a release and make it available on the release page.
Cloud build reads its instructions from the
cloudbuild.yaml file in this directory.
We use a Go program to make the tagging and branch creation process less error prone.
See this multi-module repo tagging discussion for an explanation of the path-like portion of these tags.
Go's semver-compatible version tags take the form v{major}.{minor}.{patch}:
| major | minor | patch |
|---|---|---|
| API change | enhancements | bug fixes |
| manual update | maybe auto-update | auto-update encouraged |
- If there are only bug fixes or refactors, increment
patchfrom whatever it is now. - If there are new features, increment
minor. - If there's an API change (either the Go API or the CLI behavior
with respect to CLI arguments and flags), increment
major.
The dependencies determine the release order:
| module | depends on |
|---|---|
sigs.k8s.io/kustomize/kyaml |
no local dependencies |
sigs.k8s.io/kustomize/cmd/config |
kyaml, |
sigs.k8s.io/kustomize/api |
kyaml |
sigs.k8s.io/kustomize/kustomize |
cmd/config, api |
Thus, do kyaml first, then cmd/config, etc.
⚠️ IMPORTANT: Check for release-blocking issues
We use the release-blocker tag to track issues that need to be solved before the next release. Typically, this would be a new regression introduced on the master branch and not present in the previous release. If any such issues exist, the release should be delayed.
It is also a good idea to scan any untriaged issues for potential blockers we haven't labelled yet before proceeding.
The Kubernetes OpenAPI data changes no more frequently than once per quarter. You can check the current builtin versions that kustomize is using with the following command.
kustomize openapi info
Instructions on how to get a new OpenAPI sample can be found in the OpenAPI Readme.
The release scripts expect Kustomize code to be cloned at a path ending in sigs.k8s.io/kustomize. Run all commands from that directory unless otherwise specified.
source releasing/helpers.sh
( cd cmd/gorepomod; go install . )
# Use your own token
GITHUB_TOKEN=deadbeefdeadbeef
echo $GITHUB_TOKEN | gh auth login --scopes repo --with-token
refreshMaster &&
testKustomizeRepo
While you're waiting for the tests, review the commit log. Based on the changes to be included in this release, decide whether a patch, minor or major version bump is needed: semver review.
kyaml has no intra-repo deps, so if the tests pass, it can just be released.
The default increment is a new patch version.
gorepomod release kyaml [patch|minor|major] --doIt
Note the version:
versionKyaml=v0.10.20 # EDIT THIS!
See the process of the cloud build job on the project cloud build history page.
Undraft the release on the kustomize repo release page:
- Make sure the version number is what you expect.
- Remove references to commits that aren't relevant to end users of this module (e.g. test commits, refactors).
- Make sure each commit left in the release notes includes a PR reference.
gorepomod pin kyaml --doIt &&
go mod edit -require=sigs.k8s.io/kustomize/kyaml@$versionKyaml plugin/builtin/prefixtransformer/go.mod &&
go mod edit -require=sigs.k8s.io/kustomize/kyaml@$versionKyaml plugin/builtin/suffixtransformer/go.mod &&
go mod edit -require=sigs.k8s.io/kustomize/kyaml@$versionKyaml plugin/builtin/replicacounttransformer/go.mod &&
go mod edit -require=sigs.k8s.io/kustomize/kyaml@$versionKyaml plugin/builtin/patchtransformer/go.mod &&
go mod edit -require=sigs.k8s.io/kustomize/kyaml@$versionKyaml plugin/builtin/patchjson6902transformer/go.mod
Create the PR:
createBranch pinToKyaml "Update kyaml to $versionKyaml"
createPr
Run local tests while GH runs tests in the cloud:
testKustomizeRepo
Wait for tests to pass, then merge the PR:
gh pr status
gh pr merge -m
Get back on master and do paranoia test:
refreshMaster &&
testKustomizeRepo
While you're waiting for the tests, review the commit log. Based on the changes to be included in this release, decide whether a patch, minor or major version bump is needed: semver review.
gorepomod release cmd/config [patch|minor|major] --doIt
Note the version:
versionCmdConfig=v0.9.12 # EDIT THIS!
See the process of the cloud build job on the project cloud build history page.
Undraft the release on the kustomize repo release page:
- Make sure the version number is what you expect.
- Remove references to commits that aren't relevant to end users of this module (e.g. test commits, refactors).
- Make sure each commit left in the release notes includes a PR reference.
This is the kustomize API, used by the kustomize CLI.
gorepomod pin cmd/config --doIt
Create the PR:
createBranch pinToCmdConfig "Update cmd/config to $versionCmdConfig" &&
createPr
Run local tests while GH runs tests in the cloud:
testKustomizeRepo
Wait for tests to pass, then merge the PR:
gh pr status # rinse, repeat
gh pr merge -m
Get back on master and do paranoia test:
refreshMaster &&
testKustomizeRepo
While you're waiting for the tests, review the commit log. Based on the changes to be included in this release, decide whether a patch, minor or major version bump is needed: semver review.
gorepomod release api [patch|minor|major] --doIt
Note the version:
versionApi=v0.8.10 # EDIT THIS!
See the process of the cloud build job on the project cloud build history page.
Undraft the release on the kustomize repo release page:
- Make sure the version number is what you expect.
- Remove references to commits that aren't relevant to end users of this module (e.g. test commits, refactors).
- Make sure each commit left in the release notes includes a PR reference.
gorepomod pin api --doIt
Create the PR:
createBranch pinToApi "Update api to $versionApi" &&
createPr
Run local tests while GH runs tests in the cloud:
testKustomizeRepo
Wait for tests to pass, then merge the PR:
gh pr status # rinse, repeat
gh pr merge -m
Get back on master and do paranoia test:
refreshMaster &&
testKustomizeRepo
While you're waiting for the tests, review the commit log. Based on the changes to be included in this release, decide whether a patch, minor or major version bump is needed: semver review.
gorepomod release kustomize [patch|minor|major] --doIt
See the process of the cloud build job on the project cloud build history page.
Undraft the release on the kustomize repo release page:
- Make sure the version number is what you expect.
- Remove references to commits that aren't relevant to end users of the CLI (e.g. test commits, refactors, changes that only surface in Go).
- Make sure each commit left in the release notes includes a PR reference.
-
Follow the installation instructions to install your new release and make sure it reports the expected version number.
If not, something is very wrong.
-
Visit the release page and edit the release notes as desired.
Go back into development mode, where all modules depend on in-repo code:
gorepomod unpin api --doIt &&
gorepomod unpin cmd/config --doIt &&
gorepomod unpin kyaml --doIt
Create the PR:
createBranch unpinEverything "Back to development mode; unpin the modules" &&
createPr
Run local tests while GH runs tests in the cloud:
testKustomizeRepo
Wait for tests to pass, then merge the PR:
gh pr status # rinse, repeat
gh pr merge -m
Get back on master and do paranoia test:
refreshMaster &&
testKustomizeRepo
Edit the prow-presubmit-target in the Makefile
to test examples against your new release.
sed -i "" "s/LATEST_V4_RELEASE=.*/LATEST_V4_RELEASE=v4.3.0/" Makefile
createBranch updateProwExamplesTarget "Test examples against latest release" &&
createPr
Wait for tests to pass, then merge the PR:
gh pr status # rinse, repeat
gh pr merge -m
Fork and clone the k8s.io repo.
Checkout a new branch.
Edit file k8s.gcr.io/images/k8s-staging-kustomize/images.yaml
to add the new kustomize version and the image sha256.
Image sha256 can be found in the image registry in the GCP project k8s-staging-kustomize.
Commit and push your changes. Then create a PR to k8s.io to promote the new image.
To update the version of kustomize shipped with kubectl, first fork and clone the kubernetes/kubernetes repo.
In the root of the kubernetes/kubernetes repo, run the following command:
./hack/update-kustomize.shWhen prompted, review the list of suggested module versions and make sure it matches the versions used in the latest kustomize release. If kyaml, cmd/config or api has been released more recently than kustomize/v4, do not use the more recent version.
If code used by the kustomize attachment points has changed, kubectl will fail to compile and you will need to update them. The code you'll need to change is likely in the staging/src/k8s.io/cli-runtime/pkg/resource and/or staging/src/k8s.io/kubectl/pkg/cmd/kustomize packages.
Here are some example PRs:
You can test the release script locally by running cloudbuild.sh in a container or by installing Cloud Build Local and running cloudbuild-local.sh. See each of those files for more details on their usage.