github.com/vmware/govmomi@v0.43.0/RELEASE.md (about)

     1  # How to create a `govmomi` Release on Github
     2  
     3  > **Note**
     4  >
     5  > The steps outlined in this document can only be performed by maintainers or
     6  > administrators of this project.
     7  
     8  The release automation is based on Github
     9  [Actions](https://github.com/features/actions) and has been improved over time
    10  to simplify the experience for creating `govmomi` releases.
    11  
    12  The Github Actions release [workflow](.github/workflows/govmomi-release.yaml)
    13  uses [`goreleaser`](http://goreleaser.com/) and automatically creates/pushes:
    14  
    15  - Release artifacts for `govc` and `vcsim` to the
    16    [release](https://github.com/vmware/govmomi/releases) page, including
    17    `LICENSE.txt`, `README` and `CHANGELOG`
    18  - Docker images for `vmware/govc` and `vmware/vcsim` to Docker Hub
    19  - Source code
    20  
    21  Releases are not tagged on the `main` branch, but a dedicated release branch, for example `release-0.35`.
    22  
    23  ### Verify `main` branch is up to date with the remote
    24  
    25  ```console
    26  git checkout main
    27  git fetch -avp
    28  git diff main origin/main
    29  
    30  # if your local and remote branches diverge run
    31  git pull origin/main
    32  ```
    33  
    34  > **Warning**
    35  >
    36  > These steps assume `origin` to point to the remote
    37  > `https://github.com/vmware/govmomi`, respectively
    38  > `git@github.com:vmware/govmomi`.
    39  
    40  ### Create a release branch
    41  
    42  For new releases, create a release branch from the most recent commit in
    43  `main`, e.g. `release-0.35`.
    44  
    45  ```console
    46  export RELEASE_BRANCH=release-0.35
    47  git checkout -b ${RELEASE_BRANCH}
    48  ```
    49  
    50  For maintenance/patch releases on **existing** release branches, simply checkout the existing
    51  release branch and add commits to the existing release branch.
    52  
    53  ### Verify `make docs` and `CONTRIBUTORS` are up to date
    54  
    55  > **Warning**
    56  >
    57  > Run the following commands and commit any changes to the release branch before
    58  > proceeding with the release.
    59  
    60  ```console
    61  make doc
    62  ./scripts/contributors.sh
    63  if [ -z "$(git status --porcelain)" ]; then
    64    echo "working directory clean: proceed with release"
    65  else
    66    echo "working directory dirty: please commit changes"
    67  fi
    68  
    69  # perform git add && git commit ... in case there were changes
    70  ```
    71  
    72  ### Push the release branch
    73  
    74  > **Warning**
    75  >
    76  > Do not create a tag as this will be done by the release automation.
    77  
    78  The final step is pushing the new/updated release branch.
    79  
    80  ```console
    81  git push origin ${RELEASE_BRANCH}
    82  ```
    83  
    84  ### Create a release in the Github UI
    85  
    86  Open the `govmomi` Github [repository](https://github.com/vmware/govmomi) and
    87  navigate to `Actions -> Workflows -> Release`.
    88  
    89  Click `Run Workflow` which opens a dropdown list.
    90  
    91  Select the new/updated branch, e.g. `release-0.35`, i.e. **not** the `main`
    92  branch.
    93  
    94  Specify a semantic `tag` to associate with the release, e.g. `v0.35.0`.
    95  
    96  > **Warning**
    97  >
    98  > This tag **must not** exist or the release will fail during the validation
    99  > phase.
   100  
   101  By default, a dry-run is performed to rule out most (but not all) errors during
   102  a release. If you do not want to perform a dry-run, e.g. to finally create a
   103  release, deselect the `Verify release workflow ...` checkbox.
   104  
   105  Click `Run Workflow` to kick off the workflow.
   106  
   107  After successful completion and if the newly created `tag` is the **latest**
   108  (semantic version sorted) tag in the repository, a PR is automatically opened
   109  against the `main` branch to update the `CHANGELOG`.