Skip to content

Commit

Permalink
Merge pull request #2832 from embano1/issue-2830
Browse files Browse the repository at this point in the history
  • Loading branch information
@embano1
embano1 authored Apr 27, 2022
2 parents 4c6c565 + 9ea287c commit ac1eba3
Show file tree
Hide file tree
Showing 5 changed files with 118 additions and 113 deletions.
104 changes: 53 additions & 51 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,18 +4,20 @@

First, fork the repository on GitHub to your personal account.

Note that `GOPATH` can be any directory, the example below uses `$HOME/govmomi`.
Change `$USER` below to your Github username if they are not the same.

```console
$ export GOPATH=$HOME/govmomi
$ go get github.com/vmware/govmomi

$ cd $GOPATH/src/github.com/vmware/govmomi
$ git config push.default nothing # anything to avoid pushing to vmware/govmomi by default
$ git remote rename origin vmware
$ git remote add $USER git@github.com:$USER/govmomi.git
$ git fetch $USER
Change `$USER` in the examples below to your Github username if they are not the
same.

```bash
git clone https://github.com/vmware/govmomi.git && cd govmomi

# prevent accidentally pushing to vmware/govmomi
git config push.default nothing
git remote rename origin vmware

# add your fork
git remote add $USER git@github.com:$USER/govmomi.git

git fetch -av
```

## Contribution Flow
Expand All @@ -38,40 +40,40 @@ and **supported prefixes**, e.g. `govc: <message>`.
### Example 1 - Fix a Bug in `govmomi`

```console
$ git checkout -b issue-<number> vmware/master
$ git add <files>
$ git commit -m "fix: ..." -m "Closes: #<issue-number>"
$ git push $USER issue-<number>
```bash
git checkout -b issue-<number> vmware/master
git add <files>
git commit -m "fix: ..." -m "Closes: #<issue-number>"
git push $USER issue-<number>
```

### Example 2 - Add a new (non-breaking) API to `govmomi`

```console
$ git checkout -b issue-<number> vmware/master
$ git add <files>
$ git commit -m "Add API ..." -m "Closes: #<issue-number>"
$ git push $USER issue-<number>
```bash
git checkout -b issue-<number> vmware/master
git add <files>
git commit -m "Add API ..." -m "Closes: #<issue-number>"
git push $USER issue-<number>
```

### Example 3 - Add a Feature to `govc`

```console
$ git checkout -b issue-<number> vmware/master
$ git add <files>
$ git commit -m "govc: Add feature ..." -m "Closes: #<issue-number>"
$ git push $USER issue-<number>
```bash
git checkout -b issue-<number> vmware/master
git add <files>
git commit -m "govc: Add feature ..." -m "Closes: #<issue-number>"
git push $USER issue-<number>
```
**Note**:
To register the new `govc` command package, add a blank `_` import to `govmomi/govc/main.go`.

### Example 4 - Fix a Bug in `vcsim`

```console
$ git checkout -b issue-<number> vmware/master
$ git add <files>
$ git commit -m "vcsim: Fix ..." -m "Closes: #<issue-number>"
$ git push $USER issue-<number>
```bash
git checkout -b issue-<number> vmware/master
git add <files>
git commit -m "vcsim: Fix ..." -m "Closes: #<issue-number>"
git push $USER issue-<number>
```

### Example 5 - Document Breaking (API) Changes
Expand All @@ -84,10 +86,10 @@ The text after `BREAKING:` is used in the corresponding highlighted section.
Thus these details should be stated at the body of the commit message.
Multi-line strings are supported.

```console
$ git checkout -b issue-<number> vmware/master
$ git add <files>
$ cat << EOF | git commit -F -
```bash
git checkout -b issue-<number> vmware/master
git add <files>
cat << EOF | git commit -F -
Add ctx to funcXYZ
This commit introduces context.Context to function XYZ
Expand All @@ -96,19 +98,19 @@ Closes: #1234
BREAKING: Add ctx to funcXYZ()
EOF

$ git push $USER issue-<number>
git push $USER issue-<number>
```

### Stay in sync with Upstream

When your branch gets out of sync with the vmware/master branch, use the
following to update (rebase):

```console
$ git checkout issue-<number>
$ git fetch -a
$ git rebase vmware/master
$ git push --force-with-lease $USER issue-<number>
```bash
git checkout issue-<number>
git fetch -a
git rebase vmware/master
git push --force-with-lease $USER issue-<number>
```

### Updating Pull Requests
Expand All @@ -120,25 +122,25 @@ is to assist the reviewer(s) to easily detect and review the recent changes.
In case of small PRs, it's ok to squash and force-push (see further below)
directly instead.

```console
```bash
# incorporate review feedback
$ git add .
git add .

# create a fixup commit which will be merged into your (original) <commit>
$ git commit --fixup <commit>
$ git push $USER issue-<number>
git commit --fixup <commit>
git push $USER issue-<number>
```

Be sure to add a comment to the PR indicating your new changes are ready to
review, as Github does not generate a notification when you git push.

Once the review is complete, squash and push your final commit(s):

```console
```bash
# squash all commits into one
# --autosquash will automatically detect and merge fixup commits
$ git rebase -i --autosquash vmware/master
$ git push --force-with-lease $USER issue-<number>
git rebase -i --autosquash vmware/master
git push --force-with-lease $USER issue-<number>
```

### Code Style
Expand All @@ -165,8 +167,8 @@ section in the `CHANGELOG`.
The following example creates a commit referencing the `issue: 1234` and puts
the commit message in the `govc` `CHANGELOG` section:

```console
$ git commit -s -m "govc: Add CLI command X" -m "Closes: #1234"
```bash
git commit -s -m "govc: Add CLI command X" -m "Closes: #1234"
```

Currently the following prefixes are used:
Expand Down
4 changes: 2 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,8 +39,8 @@ See [godoc.org][godoc] for documentation.

### govmomi (Package)

```console
$ go get -u github.com/vmware/govmomi
```bash
go get -u github.com/vmware/govmomi
```

### Binaries and Docker Images for `govc` and `vcsim`
Expand Down
65 changes: 33 additions & 32 deletions govc/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,22 +16,22 @@ You can find prebuilt `govc` binaries on the [releases page](https://github.com/

You can download and install a binary locally like this:

```console
```bash
# extract govc binary to /usr/local/bin
# note: the "tar" command must run with root permissions
$ curl -L -o - "https://github.com/vmware/govmomi/releases/latest/download/govc_$(uname -s)_$(uname -m).tar.gz" | tar -C /usr/local/bin -xvzf - govc
curl -L -o - "https://github.com/vmware/govmomi/releases/latest/download/govc_$(uname -s)_$(uname -m).tar.gz" | tar -C /usr/local/bin -xvzf - govc
```

### Source

#### Install via `go get`
#### Install via `go install`

To build `govc` from source, first install the [Go
toolchain](https://golang.org/dl/). You can then install the latest `govc` from
Github using:

```console
$ go get -u github.com/vmware/govmomi/govc
```bash
go install github.com/vmware/govmomi/govc@latest
```

**Note:** `govmomi` and its binaries use [Go
Expand All @@ -46,8 +46,8 @@ source.
If you've made local modifications to the repository at
`$GOPATH/src/github.com/vmware/govmomi`, you can install using:

```console
$ go install github.com/vmware/govmomi/govc
```bash
go install github.com/vmware/govmomi/govc
```

#### Install via `goreleaser`
Expand All @@ -61,18 +61,18 @@ defined in [.goreleaser.yaml](./../.goreleaser.yml) and automatically set as
Install `goreleaser` as per the installation
[instructions](https://goreleaser.com/install/), then:

```console
$ git clone https://github.com/vmware/govmomi.git
$ cd govmomi
```bash
git clone https://github.com/vmware/govmomi.git
cd govmomi

# pick a tag (>=v0.25.0)
$ RELEASE=v0.25.0
RELEASE=v0.25.0

$ git checkout ${RELEASE}
git checkout ${RELEASE}

# build for the host OS/ARCH, otherwise omit --single-target
# binaries are placed in respective subdirectories in ./dist/
$ goreleaser build --rm-dist --single-target
goreleaser build --rm-dist --single-target
```

## Usage
Expand Down Expand Up @@ -122,21 +122,21 @@ using environment variables. The following environment variables are used by

* `GOVC_TLS_CA_CERTS`: Override system root certificate authorities.

```console
$ export GOVC_TLS_CA_CERTS=~/.govc_ca.crt
```bash
export GOVC_TLS_CA_CERTS=~/.govc_ca.crt
# Use path separator to specify multiple files:
$ export GOVC_TLS_CA_CERTS=~/ca-certificates/bar.crt:~/ca-certificates/foo.crt
export GOVC_TLS_CA_CERTS=~/ca-certificates/bar.crt:~/ca-certificates/foo.crt
```

* `GOVC_TLS_KNOWN_HOSTS`: File(s) for thumbprint based certificate verification.

Thumbprint based verification can be used in addition to or as an alternative to
`GOVC_TLS_CA_CERTS` for self-signed certificates. Example:

```console
$ export GOVC_TLS_KNOWN_HOSTS=~/.govc_known_hosts
$ govc about.cert -u host -k -thumbprint | tee -a $GOVC_TLS_KNOWN_HOSTS
$ govc about -u user:pass@host
```bash
export GOVC_TLS_KNOWN_HOSTS=~/.govc_known_hosts
govc about.cert -u host -k -thumbprint | tee -a $GOVC_TLS_KNOWN_HOSTS
govc about -u user:pass@host
```

* `GOVC_TLS_HANDSHAKE_TIMEOUT`: Limits the time spent performing the TLS handshake.
Expand Down Expand Up @@ -193,7 +193,7 @@ The`-debug` flag traces vSphere API calls similar to the `-trace` flag, but save
When the `-debug` flag is specified, the default behavior is to put the output in `~/.govmomi/debug/<run timestamp>`.
In that directory will be four (4) files per API call.

```
```bash
1-0001.req.headers #headers from the request sent to the API
1-0001.req.xml #body content from request sent to the API
1-0001.res.headers #headers from the response from the API
Expand Down Expand Up @@ -229,21 +229,22 @@ by setting the debug path to a dash: `export GOVC_DEBUG_PATH=-`

If you're using environment variables to set `GOVC_URL`, verify the values are set as expected:
```console
$ govc env
```bash
govc env
```
### Connection issues
Check your proxy settings:
```console
$ env | grep -i https_proxy
```bash
env | grep -i https_proxy
```
Test connection using curl:
```console
$ curl --verbose -k -X POST https://x.x.x.x/sdk
Test connection using `curl`:
```bash
curl --verbose -k -X POST https://x.x.x.x/sdk
```
### MSYS2 (Windows)
Expand All @@ -258,8 +259,8 @@ cookies, resulting in a `NotAuthenticated` error. For example, running `govc`
directly against the vCenter vpxd endpoint at `http://127.0.0.1:8085`. Set the
environment variable `GOVMOMI_INSECURE_COOKIES=true` to workaround this:

```console
$ GOVMOMI_INSECURE_COOKIES=true govc ls -u http://user:pass@127.0.0.1:8085
```bash
GOVMOMI_INSECURE_COOKIES=true govc ls -u http://user:pass@127.0.0.1:8085
```

## Examples
Expand Down Expand Up @@ -290,8 +291,8 @@ When new `govc` commands or flags are added, the PATCH version will be
incremented. This enables you to require a minimum version from within a
script, for example:

```console
$ govc version -require 0.24
```bash
govc version -require 0.24
```

## Projects using `govc`
Expand Down
6 changes: 4 additions & 2 deletions vapi/library/finder/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,8 @@ While a system that has few content library objects benefits from wildcard searc
## `govc library.ls`

### Listing all the objects in the content library
```shell

```console
$ govc library.ls '*/*/'
/ISOs/CentOS-7-x86_64-Minimal-1804/CentOS-7-x86_64-Minimal-1804.iso
/ISOs/CoreOS Production/coreos_production_iso_image.iso
Expand Down Expand Up @@ -72,7 +73,8 @@ $ govc library.ls '*/*/'
## `govc library.info`

### Getting the info for all the objects in the content library
```shell

```console
$ govc library.info '*/*/'
Name: CentOS-7-x86_64-Minimal-1804.iso
Path: /ISOs/CentOS-7-x86_64-Minimal-1804/CentOS-7-x86_64-Minimal-1804.iso
Expand Down
Loading

0 comments on commit ac1eba3

Please sign in to comment.