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
andvcsim
to the release page, includingLICENSE.txt
,README
andCHANGELOG
- Docker images for
vmware/govc
andvmware/vcsim
to Docker Hub - Source code
Starting with release tag v0.29.0
, releases are not tagged on the main
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.
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.
git checkout main
git fetch -avp
git diff main origin/main
# if your local and remote branches diverge run
git pull origin/main
Warning
These steps assume
origin
to point to the remotehttps://github.com/vmware/govmomi
, respectively[email protected]:vmware/govmomi
.
For new releases, create a release branch from the most recent commit in
main
, 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.
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
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}
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 main
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 main
branch to update the CHANGELOG
. Please review and merge
accordingly.
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.
git checkout main
git fetch -avp
git diff main origin/main
# if your local and remote branches diverge run
git pull origin/main
Warning
These steps assume
origin
to point to the remotehttps://github.com/vmware/govmomi
, respectively[email protected]:vmware/govmomi
.
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/
!
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
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
git tag -a ${RELEASE_VERSION} -m "Release ${RELEASE_VERSION}"
# Will trigger Github Actions Release Workflow
git push --atomic origin ${RELEASE_BRANCH} refs/tags/${RELEASE_VERSION}
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).