Repository: vmware/govmomi
Pull request #2603 (2021-09-30 16:05:46)

Update PR and RELEASE docs
## Description

Closes: #2478

- Update `RELEASE` instructions to make sure govc docs are up2date
- Add workflow to catch govc docs inconsistencies
- Remove test details in PR instructions
- update govc `USAGE` so the workflow passes

Signed-off-by: Michael Gasch <mgasch@vmware.com>

## Type of change

Please mark options that are relevant:

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to
  not work as expected)
- [x] This change requires a documentation update
- [x] Build related change

## How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide
instructions so we can reproduce. If applicable, please also list any relevant
details for your test configuration.

- [x] Test runs with non-updated govc docs to see if workflow fails

## Checklist:

- [x] My code follows the CONTRIBUTION [guidelines](./../CONTRIBUTING.md) of
  this project
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [ ] I have added tests that prove my fix is effective or that my feature works
- [x] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged


Patch:
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 93f06de1..ba8105ff 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -15,6 +15,7 @@ Please mark options that are relevant:
 - [ ] Breaking change (fix or feature that would cause existing functionality to
   not work as expected)
 - [ ] This change requires a documentation update
+- [ ] Build related change
 
 ## How Has This Been Tested?
 
@@ -25,11 +26,6 @@ details for your test configuration.
 - [ ] Test Description 1
 - [ ] Test Description 2
 
-**Test Configuration**:
-* Toolchain:
-* SDK:
-* (add more if needed)
-
 ## Checklist:
 
 - [ ] My code follows the CONTRIBUTION [guidelines](./../CONTRIBUTING.md) of
diff --git a/RELEASE.md b/RELEASE.md
index 2d3c33d0..45ed3900 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -19,18 +19,33 @@ of this project.
 ## Verify `master` branch is up to date with the remote
 
 ```console
-$ git checkout master
-$ git fetch -avp
-$ git diff master origin/master
+git checkout master
+git fetch -avp
+git diff master origin/master
 
 # if your local and remote branches diverge run
-$ git pull origin/master
+git pull origin/master
 ```
 
 ⚠️ **Note:** These steps assume `origin` to point to the remote
 `https://github.com/vmware/govmomi`, respectively
 `git@github.com:vmware/govmomi`.
 
+## Verify `make docs` and `CONTRIBUTORS` are up to date
+
+⚠️ Run the following commands and commit (PR) any changes 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
+```
+
 
 ## Set `RELEASE_VERSION` variable
 
@@ -39,26 +54,25 @@ This variable is used and referenced in the subsequent commands. Set it to the
 versioning](https://semver.org/) scheme:
 
 ```console
-$ export RELEASE_VERSION=v0.25.0
+export RELEASE_VERSION=v0.27.0
 ```
 
 ## Create the Git Tag
 
 ```console
-$ git tag -a ${RELEASE_VERSION} -m "Release ${RELEASE_VERSION}"
+git tag -a ${RELEASE_VERSION} -m "Release ${RELEASE_VERSION}"
 ```
 
 ## Push the new Tag
 
 ```console
 # Will trigger Github Actions Release Workflow
-$ git push origin refs/tags/${RELEASE_VERSION}
+git push origin refs/tags/${RELEASE_VERSION}
 ```
 
 ## Verify Github Action Release Workflow
 
-After pushing a new release tag, the status of the
-workflow can be inspected
+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")
diff --git a/govc/USAGE.md b/govc/USAGE.md
index 272778bb..ea011b4f 100644
--- a/govc/USAGE.md
+++ b/govc/USAGE.md
@@ -324,6 +324,8 @@ but appear via `govc $cmd -h`:
  - [vm.vnc](#vmvnc)
  - [volume.ls](#volumels)
  - [volume.rm](#volumerm)
+ - [vsan.change](#vsanchange)
+ - [vsan.info](#vsaninfo)
 
 </details>
 
@@ -402,10 +404,12 @@ Change configuration of the given clusters.
 Examples:
   govc cluster.change -drs-enabled -vsan-enabled -vsan-autoclaim ClusterA
   govc cluster.change -drs-enabled=false ClusterB
+  govc cluster.change -drs-vmotion-rate=4 ClusterC
 
 Options:
   -drs-enabled=<nil>     Enable DRS
   -drs-mode=             DRS behavior for virtual machines: manual, partiallyAutomated, fullyAutomated
+  -drs-vmotion-rate=0    Aggressiveness of vMotions (1-5)
   -ha-enabled=<nil>      Enable HA
   -vsan-autoclaim=<nil>  Autoclaim storage on cluster hosts
   -vsan-enabled=<nil>    Enable vSAN
@@ -3043,8 +3047,10 @@ Examples:
 Options:
   -cluster=              Cluster [GOVC_CLUSTER]
   -ds=                   Datastore [GOVC_DATASTORE]
+  -e=false               Include extra configuration
   -folder=               Inventory folder [GOVC_FOLDER]
   -host=                 Host system [GOVC_HOST]
+  -m=false               Preserve MAC-addresses on network adapters
   -ovf=false             Clone as OVF (default is VM Template)
   -pool=                 Resource pool [GOVC_RESOURCE_POOL]
   -profile=              Storage profile
@@ -3347,16 +3353,17 @@ Options:
 ## library.update
 
 ```
-Usage: govc library.update [OPTIONS] NAME
+Usage: govc library.update [OPTIONS] PATH
 
-Update library.
+Update library or item PATH.
 
 Examples:
-  govc library.update -d "new description" -n "new-name" current-name
+  govc library.update -d "new library description" -n "new-name" my-library
+  govc library.update -d "new item description" -n "new-item-name" my-library/my-item
 
 Options:
-  -d=                    Library description
-  -n=                    Library name
+  -d=                    Library or item description
+  -n=                    Library or item name
 ```
 
 ## license.add
@@ -3783,6 +3790,22 @@ followed by the value to match.
 The '-R' flag sets the Filter using the given XML encoded request, which can be captured by 'vcsim -trace' for example.
 It can be useful for replaying property filters created by other clients and converting filters to Go code via '-O -dump'.
 
+The '-type' flag value can be a managed entity type or one of the following aliases:
+
+  a    VirtualApp
+  c    ClusterComputeResource
+  d    Datacenter
+  f    Folder
+  g    DistributedVirtualPortgroup
+  h    HostSystem
+  m    VirtualMachine
+  n    Network
+  o    OpaqueNetwork
+  p    ResourcePool
+  r    ComputeResource
+  s    Datastore
+  w    DistributedVirtualSwitch
+
 Examples:
   govc object.collect - content
   govc object.collect -s HostSystem:ha-host hardware.systemInfo.uuid
@@ -5681,3 +5704,33 @@ Examples:
 Options:
 ```
 
+## vsan.change
+
+```
+Usage: govc vsan.change [OPTIONS] CLUSTER
+
+Change vSAN configuration.
+
+Examples:
+  govc vsan.change -unmap-enabled ClusterA # enable unmap
+  govc vsan.change -unmap-enabled=false ClusterA # disable unmap
+
+Options:
+  -unmap-enabled=<nil>   Enable Unmap
+```
+
+## vsan.info
+
+```
+Usage: govc vsan.info [OPTIONS] CLUSTER...
+
+Display vSAN configuration.
+
+Examples:
+  govc vsan.info
+  govc vsan.info ClusterA
+  govc vsan.info -json
+
+Options:
+```
+


Test patch:
diff --git a/.github/workflows/govmomi-govc-tests.yaml b/.github/workflows/govmomi-govc-tests.yaml
index c9e6efc7..aa95de88 100644
--- a/.github/workflows/govmomi-govc-tests.yaml
+++ b/.github/workflows/govmomi-govc-tests.yaml
@@ -59,3 +59,31 @@ jobs:
 
       - name: Run ${{ matrix.cmd }}
         run: make ${{ matrix.cmd }}
+
+  govc-docs:
+    name: Verify govc docs are up2date
+    strategy:
+      matrix:
+        go-version: ["1.16"]
+        platform: ["ubuntu-18.04"]
+    runs-on: ${{ matrix.platform }}
+    timeout-minutes: 3
+    steps:
+      - name: Set up Go ${{ matrix.go-version }}
+        uses: actions/setup-go@v2
+        with:
+          go-version: ${{ matrix.go-version }}
+        id: go
+      - name: Check out code
+        uses: actions/checkout@v2
+      - name: Run "make doc"
+        run: |
+          make doc
+          if [ -z "$(git status --porcelain)" ]; then 
+            echo "govc/USAGE.md is up2date..."
+          else 
+            echo "dirty working directory (diff):"
+            git --no-pager diff
+            echo "::error file=govc/USAGE.md::Run make doc to update USAGE.md"
+            exit 1
+          fi