kubernetes/vendor/github.com/vmware/govmomi/RELEASE.md

How to create a govmomi Release on Github

Note

The steps outlined in this document can only be performed by maintainers or administrators of this project.

The release automation is based on Github Actions and has been improved over time to simplify the experience for creating govmomi releases.

The Github Actions release workflow uses goreleaser and automatically creates/pushes:

• Release artifacts for govc and vcsim to the release page, including LICENSE.txt, README and CHANGELOG
• Docker images for vmware/govc and vmware/vcsim to Docker Hub
• Source code

Starting with release tag v0.29.0, releases are not tagged on the master branch anymore but a dedicated release branch, for example release-0.29. This process has already been followed for patch releases and back-ports.

Warning

If you create a release after the v0.29.0 tag, start here. To create a release with an older tag, e.g. cherrypick or back-port, continue here.

Creating a release after Version v0.29.0

The release process from v0.29.0 has been further simplified and is done through the Github UI. The only pre-requirement is creating a release branch, which can be done through the Github UI or git CLI.

This guide describes the CLI process.

Verify master branch is up to date with the remote

git checkout master
git fetch -avp
git diff master origin/master

# if your local and remote branches diverge run
git pull origin/master

Warning

These steps assume origin to point to the remote https://github.com/vmware/govmomi, respectively git@github.com:vmware/govmomi.

Create a release branch

For new releases, create a release branch from the most recent commit in master, e.g. release-0.30.

export RELEASE_BRANCH=release-0.30
git checkout -b ${RELEASE_BRANCH}

For maintenance/patch releases on existing release branches after tag v0.29.0 simply checkout the existing release branch and add commits to the existing release branch.

Verify make docs and CONTRIBUTORS are up to date

Warning

Run the following commands and commit any changes to the release branch before proceeding with the release.

make doc
./scripts/contributors.sh
if [ -z "$(git status --porcelain)" ]; then 
  echo "working directory clean: proceed with release"
else 
  echo "working directory dirty: please commit changes"
fi

# perform git add && git commit ... in case there were changes

Push the release branch

Warning

Do not create a tag as this will be done by the release automation.

The final step is pushing the new/updated release branch.

git push origin ${RELEASE_BRANCH}

Create a release in the Github UI

Open the govmomi Github repository and navigate to Actions -> Workflows -> Release.

Click Run Workflow which opens a dropdown list.

Select the new/updated branch, e.g. release-0.30, i.e. not the master branch.

Specify a semantic tag to associate with the release, e.g. v0.30.0.

Warning

This tag must not exist or the release will fail during the validation phase.

By default, a dry-run is performed to rule out most (but not all) errors during a release. If you do not want to perform a dry-run, e.g. to finally create a release, deselect the Verify release workflow ... checkbox.

Click Run Workflow to kick off the workflow.

After successful completion and if the newly created tag is the latest (semantic version sorted) tag in the repository, a PR is automatically opened against the master branch to update the CHANGELOG. Please review and merge accordingly.

Creating a release before Version v0.29.0

The release process before v0.29.0 differs since it's based on manually creating and pushing tags. Here, on every new tag matching v* pushed to the repository a Github Action Release Workflow is executed.

Verify master branch is up to date with the remote

git checkout master
git fetch -avp
git diff master origin/master

# if your local and remote branches diverge run
git pull origin/master

Warning

These steps assume origin to point to the remote https://github.com/vmware/govmomi, respectively git@github.com:vmware/govmomi.

Create a release branch

Pick a reference (commit, branch or tag) before the v0.29.0 tag and create a release branch from there.

The following example creates a cherrypick release (v0.28.1) based on the v0.28.0 tag.

export RELEASE_BRANCH=release-0.28
git checkout -b ${RELEASE_BRANCH} v0.28.0

Optionally, incorporate (cherry-pick) commits into the branch.

Warning

Make sure that these commits/ranges do not contain commits after the v0.29.0 tag which include release automation changes, i.e. files in .github/workflows/!

Verify make docs and CONTRIBUTORS are up to date

Warning

Run the following commands and commit any changes to the release branch before proceeding with the release.

make doc
./scripts/contributors.sh
if [ -z "$(git status --porcelain)" ]; then 
  echo "working directory clean: proceed with release"
else 
  echo "working directory dirty: please commit changes"
fi

# perform git add && git commit ... in case there were changes

Set RELEASE_VERSION variable

This variable is used and referenced in the subsequent commands. Set it to the upcoming release version, adhering to the semantic versioning scheme:

export RELEASE_VERSION=v0.28.1

Create the Git Tag

git tag -a ${RELEASE_VERSION} -m "Release ${RELEASE_VERSION}"

Push the new Tag

# Will trigger Github Actions Release Workflow
git push --atomic origin ${RELEASE_BRANCH} refs/tags/${RELEASE_VERSION}

Verify Github Action Release Workflow

After pushing a new release tag, the status of the workflow can be inspected here.

After a successful release, a pull request is automatically created by the Github Actions bot to update the CHANGELOG. This CHANGELOG.md is also generated with git-chglog but uses a slightly different template (.chglog/CHANGELOG.tpl.md) for rendering (issue/PR refs are excluded).