This document describes how to perform a semver release of one of the Go modules in this repository.
These modules release independently.
See this multi-module repo tagging discussion
for an explanation of the foo/v2.3.0 tags applied below.
| Module Description | Module Prefix | Ex. Tag | Ex. Branch Name |
|---|---|---|---|
| kustomize executable | sigs.k8s.io/kustomize/kustomize |
kustomize/v3.2.2 | release-kustomize-v3.2.2 |
| kustomize Go API | sigs.k8s.io/kustomize/api |
api/v0.1.0 | release-api-v0.1 |
| pluginator executable | sigs.k8s.io/kustomize/pluginator |
pluginator/v1.0.0 | release-pluginator-v1.0 |
The kustomize program, a CLI for performing
k8s-aware structured edits to YAML in k8s resource
files.
There's only one public package in this module.
It's called main, it's therefore unimportable,
and it holds the kustomize executable.
Executable files appear for various operating systems on the release page. The tag appears in the URL, e.g. kustomize/v3.2.1.
See the installation instructions to perform an install.
This is the kustomize Go API.
The packages in this module are used by API clients,
like the kustomize program itself, and programs
in other repositories, e.g. kubectl.
They include methods to read, edit and emit
modified YAML.
Go consumers of this API will have a go.mod file
requiring this module at a particular tag, e.g.
require sigs.k8s.io/kustomize/api v0.1.0
This is a Go library-only release, so the only
artifact per se is the repo tag, in the form api/v1.2.3,
that API clients can require from their go.mod file.
Release notes should appear on the release page.
There's a toy executable called api, which, if
run, prints the API release provenance data, but it's of
no practical use to an API client.
The pluginator program, a code generator that
converts Go plugins to conventional statically
linkable library code.
There's only one package in this module.
It's called main, it's therefore unimportable,
and it holds the pluginator executable.
At the time of writing this binary is only of interest to someone writing a new builtin transformer or generator. See the plugin documentation. Its dependence on the API is primarily for plugin-related constants, not logic, and will only change if there's some change in how plugins are constructed (presumably infrequently).
Executables appear on the release page. The tag appears in the URL, e.g. pluginator/v1.0.0.
TODO: script what follows, so someone can enter
go run ./releasing/release.go kustomize minor # or: # go run ./releasing/release.go api patch # go run ./releasing/release.go pluginator minorThe program would look at the existing remote tags, confirm sanity and increment the appropriate major/minor/patch component, create the right branch and tag, etc. No more bash please.
At any given moment, the repository's master branch is passing all its tests and contains code one could release.
git fetch upstream
git checkout master
git rebase upstream/master
module=pluginator # The pluginator executable
module=kustomize # The kustomize executable
module=api # The API
Local:
git tag -l | grep $module
Remote:
git ls-remote --tags upstream | grep $module
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.
major=0; minor=1; patch=0
Every module release occurs on it's own git branch.
The branch name doesn't include the patch number, since the branch accumulates patch releases.
TODO: define procedure for doing a cherrypick (committing a patch) to a release branch that already exists.
Name the branch:
branch="release-${module}-v${major}.${minor}"
echo "branch=$branch"
Create it:
git checkout -b $branch
tag="${module}/v${major}.${minor}.${patch}"
echo "tag=$tag"
Only do this if releasing one of the executables (kustomize or pluginator).
In this repository, an executable in development
on the master branch typically depends on the API
also in development on the master branch. This is
achieved via a replace directive in the
executable's go.mod file.
A released executable, however, must depend on a specific release of the API. For this reason, it's typical, but not required, to release an executable immediately after releasing the API, updating the API version that the executable requires.
# Update the following as needed, obviously.
# git checkout -b pinTheRelease
# go mod edit -dropreplace=sigs.k8s.io/kustomize/api $module/go.mod
# go mod edit -require=sigs.k8s.io/kustomize/[email protected] $module/go.mod
# git commit -a -m "Drop API module replacement"
git push -f upstream $branch
Must delete the tag before re-pushing it.
Delete the tag locally:
git tag --delete $tag
Delete it upstream:
# Disable push protection:
git remote set-url --push upstream [email protected]:kubernetes-sigs/kustomize.git
# The empty space before the colon effectively means delete the tag.
git push upstream :refs/tags/$tag
# Enable push protection:
git remote set-url --push upstream no_push
Optionally visit the release page and delete (what has now become) the draft release for that version.
git tag -a $tag -m "Release $tag on branch $branch"
Move the latest_kustomize tag:
git tag -d latest_kustomize
git push upstream :latest_kustomize
git tag -a latest_kustomize
Install cloud-build-local, then run localbuild.sh:
./releasing/localbuild.sh $module
This should create release artifacts in a local directory.
Push the tag:
git remote set-url --push upstream [email protected]:kubernetes-sigs/kustomize.git
git push upstream $tag
git push upstream latest_kustomize
git remote set-url --push upstream no_push
This triggers a job in Google Cloud Build to put a new release on the release page.
Visit the release page and edit the release notes as desired.