From 2d1b52ff159e67f25cd49dd056751734fa9b620f Mon Sep 17 00:00:00 2001 From: Doug MacEachern Date: Thu, 8 Feb 2024 16:24:48 -0800 Subject: [PATCH] docs: update release doc Closes #3284 --- .mailmap | 3 ++ CONTRIBUTORS | 6 +++ README.md | 6 --- RELEASE.md | 144 +++++---------------------------------------------- 4 files changed, 23 insertions(+), 136 deletions(-) diff --git a/.mailmap b/.mailmap index 2bd0b82ed..8638b7f3a 100644 --- a/.mailmap +++ b/.mailmap @@ -13,6 +13,8 @@ Balu Dontu BaluDontu Bruce Downs Bruce Downs Bruce Downs +Bryan Venteicher +Brian Rak Clint Greenwood Cédric Blomart Cédric Blomart cedric @@ -25,6 +27,7 @@ Fabio Rapposelli Faiyaz Ahmed Faiyaz Ahmed Faiyaz Ahmed Faiyaz Ahmed Faiyaz Ahmed Faiyaz Ahmed +Hakan Halil <25109775+HakanSunay@users.noreply.github.com> Henrik Hodne Ian Eyberg Jeremy Canady diff --git a/CONTRIBUTORS b/CONTRIBUTORS index 082884483..5f269f130 100644 --- a/CONTRIBUTORS +++ b/CONTRIBUTORS @@ -52,7 +52,9 @@ Brian McClain Brian Rak brian57860 Bruce Downs +Bruno Meneguello <1322552+bkmeneguello@users.noreply.github.com> Bryan Venteicher +C S P Nanda Carsten Grohmann Cheng Cheng Chethan Venkatesh @@ -80,6 +82,7 @@ Defa demarey Deric Crago Deyan Popov +Dinesh Bhat <35480850+dbhat-arkin@users.noreply.github.com> ditsuke Divyen Patel Dnyanesh Gate @@ -97,6 +100,7 @@ Essodjolo KAHANAM Ethan Kaley Evan Chu Fabio Rapposelli +fabriziopandini Faiyaz Ahmed Federico Pellegatta <12744504+federico-pellegatta@users.noreply.github.com> forkbomber @@ -198,6 +202,7 @@ rconde01 rHermes Rianto Wahyudi Ricardo Katz +rmcqueen Robin Watkins Rowan Jacobs Roy Ling @@ -246,6 +251,7 @@ Uwe Bessle Vadim Egorov Vamshik Shetty Vikram Krishnamurthy +Vipul Kotkar volanja Volodymyr Bobyr Waldek Maleska diff --git a/README.md b/README.md index 73975150c..13ba3bf30 100644 --- a/README.md +++ b/README.md @@ -31,12 +31,6 @@ The code in the `govmomi` package is a wrapper for the code that is generated fr ## Installation -### govmomi (Package) - -```bash -go get -u github.com/vmware/govmomi -``` - ### Binaries and Docker Images for `govc` and `vcsim` Installation instructions, released binaries, and Docker images are documented in the respective README files of [`govc`][govc] and [`vcsim`][vcsim]. diff --git a/RELEASE.md b/RELEASE.md index 3c0965a83..58b978a50 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -1,6 +1,6 @@ # How to create a `govmomi` Release on Github -> **Note** +> **Note** > > The steps outlined in this document can only be performed by maintainers or > administrators of this project. @@ -18,24 +18,7 @@ uses [`goreleaser`](http://goreleaser.com/) and automatically creates/pushes: - 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 `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](#creating-a-release-after-v0290). To create a release with an older -> tag, e.g. cherrypick or back-port, continue -> [here](#creating-a-release-before-v0290). - -## 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. +Releases are not tagged on the `main` branch, but a dedicated release branch, for example `release-0.35`. ### Verify `main` branch is up to date with the remote @@ -48,7 +31,7 @@ git diff main origin/main git pull origin/main ``` -> **Warning** +> **Warning** > > These steps assume `origin` to point to the remote > `https://github.com/vmware/govmomi`, respectively @@ -57,30 +40,29 @@ git pull origin/main ### Create a release branch For new releases, create a release branch from the most recent commit in -`main`, e.g. `release-0.30`. +`main`, e.g. `release-0.35`. ```console -export RELEASE_BRANCH=release-0.30 +export RELEASE_BRANCH=release-0.35 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. +For maintenance/patch releases on **existing** release branches, 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. ```console make doc ./scripts/contributors.sh -if [ -z "$(git status --porcelain)" ]; then +if [ -z "$(git status --porcelain)" ]; then echo "working directory clean: proceed with release" -else +else echo "working directory dirty: please commit changes" fi @@ -93,7 +75,7 @@ fi > > Do not create a tag as this will be done by the release automation. -The final step is pushing the new/updated release branch. +The final step is pushing the new/updated release branch. ```console git push origin ${RELEASE_BRANCH} @@ -106,10 +88,10 @@ 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` +Select the new/updated branch, e.g. `release-0.35`, i.e. **not** the `main` branch. -Specify a semantic `tag` to associate with the release, e.g. `v0.30.0`. +Specify a semantic `tag` to associate with the release, e.g. `v0.35.0`. > **Warning** > @@ -124,102 +106,4 @@ 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. - -## 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 `main` branch is up to date with the remote - -```console -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 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. - -```console -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. - -```console -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](https://semver.org/) scheme: - -```console -export RELEASE_VERSION=v0.28.1 -``` - -### Create the Git Tag - -```console -git tag -a ${RELEASE_VERSION} -m "Release ${RELEASE_VERSION}" -``` - -### Push the new Tag - -```console -# 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](https://github.com/vmware/govmomi/actions/workflows/govmomi-release.yaml). - -![Release](static/release-workflow.png "Successful Release Run") - -After a successful release, a pull request is automatically created by the -Github Actions bot to update the [CHANGELOG](CHANGELOG.md). 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). +against the `main` branch to update the `CHANGELOG`.