Merge pull request #9 from circleci/usage

Improve CLI usage docs and introduce CONTRIBUTING.md

CONTRIBUTING.md

@@ -0,0 +1,74 @@
+# Contributing to the CLI
+
+If you're looking to contribute to this project, there's a few things you should know.
+
+First, make sure you go through the [README](README.md).
+
+Second, it's written in Go. If you are new to Go, we recommend the following resources:
+
+* [A Tour of Go](https://tour.golang.org/welcome/1)
+* [The Go documentation](https://golang.org/doc/)
+
+## Managing Dependencies
+
+We use `dep` for vendoring our depencencies:
+https://github.com/golang/dep
+
+If you want to update or modify any dependencies you will need to install it.
+
+You can do so on MacOS:
+
+```
+$ brew install dep
+$ brew upgrade dep
+```
+
+Or on Linux, etc:
+
+```
+$ curl https://raw.githubusercontent.com/golang/dep/master/install.sh | sh
+```
+
+To make sure dependencies are installed:
+
+```
+$ dep ensure
+```
+
+## Linting your code
+
+We use [`gometalinter`](github.com/alecthomas/gometalinter) for linting.
+
+You can install it via `$ make dev` or manually with:
+
+```
+$ go get -u github.com/alecthomas/gometalinter
+$ gometalinter --install
+```
+
+Then you can run it with `$ make lint`.
+
+There is also a `coverage` job as part of the build which will lint any code you commit.
+
+## Editor support
+
+Go has great tooling such as [`gofmt`](https://golang.org/cmd/gofmt/) and [`goimports`](https://godoc.org/golang.org/x/tools/cmd/goimports).
+
+In particular, **please be sure to `gofmt` your code before committing**.
+
+You can install `goimport` via:
+
+```
+$ go get golang.org/x/tools/cmd/goimports
+```
+
+The golang blog post ["go fmt your code"](https://blog.golang.org/go-fmt-your-code) has a lot more info `gofmt`. To get it setup with [vim](https://github.com/fatih/vim-go) or [emacs](https://github.com/dominikh/go-mode.el).
+
+For example, I've the following in my `.emacs.d/init.el`:
+
+```
+(setq gofmt-command "goimports")
+(require 'go-mode)
+(add-hook 'before-save-hook 'gofmt-before-save)
+(require 'go-rename)
+```

Makefile

@@ -4,17 +4,27 @@ SHA=$(shell git rev-parse --short HEAD)
 
 GOFILES = $(shell find . -name '*.go' -not -path './vendor/*')
 
+OS = $(shell uname)
+
 CLIPATH=github.com/circleci/circleci-cli
 
 EXECUTABLE=circleci-cli
 BUILD_DIR=build
 
-.PHONY: build/linux
+.PHONY: build
+build:
+ifeq ($(OS), Darwin)
+	GOOS=darwin GOARCH=amd64 go build -o $(BUILD_DIR)/darwin/amd64/$(EXECUTABLE)
+else ifeq ($(OS), Linux)
+	GOOS=linux GOARCH=amd64 go build -o $(BUILD_DIR)/linux/amd64/$(EXECUTABLE)
+endif
+
+.PHONY: build/*
 $(BUILD_DIR)/%/amd64/$(EXECUTABLE): $(GOFILES)
 	GOOS=$* GOARCH=amd64 CGO_ENABLED=0 go build $(LDFLAGS) -o $(BUILD_DIR)/$*/amd64/$(EXECUTABLE) .
 
-.PHONY: build
-build: $(BUILD_DIR)/darwin/amd64/$(EXECUTABLE) $(BUILD_DIR)/linux/amd64/$(EXECUTABLE)
+.PHONY: build-all
+build-all: $(BUILD_DIR)/darwin/amd64/$(EXECUTABLE) $(BUILD_DIR)/linux/amd64/$(EXECUTABLE)
 
 .PHONY: clean
 clean:
@@ -27,7 +37,7 @@ test:
 
 .PHONY: cover
 cover:
-	go test -coverprofile=coverage.txt -covermode=count ./...
+	go test -race -coverprofile=coverage.txt ./...
 
 .PHONY: lint
 lint:

README.md

@@ -4,29 +4,31 @@ This project is the seed for CircleCI's new command-line application.
 
 ## Requirements
 
-* Go 1.9+
+* Go 1.10+
 * Make
 * ...
 
-It's written in Go. If you are new to Go, we recommend the following resources:
-
-* [A Tour of Go](https://tour.golang.org/welcome/1)
-* [The Go documentation](https://golang.org/doc/)
-
-## Development
+## Getting Started
 
 You should already have [installed Go](https://golang.org/doc/install) and setup your [workspace](https://golang.org/doc/code.html#Workspaces).
 
 This includes setting a valid `$GOPATH`.
 
 ### 1. Get the repo
 
+TODO: make this easier once repo is public
+
 ```
-$ go get -u github.com/circleci/circleci-cli
-$ cd $GOPATH/src/github.com/circleci/circleci-cli
+# Setup circleci source in your $GOPATH
+$ mkdir -p $GOPATH/src/github.com/circleci
+$ cd $GOPATH/src/github.com/circleci
+
+# Clone the repo
+$ git clone [email protected]/circleci/circleci-cli
+$ cd circleci-cli
 ```
 
-### 2. Build it
+### 2. Build the binary
 
 ```
 $ make
@@ -35,7 +37,7 @@ $ make
 ### 3. Run Diagnostic check
 
 ```
-$ ./build/target/linux/amd64/circleci-cli diagnostic
+$ ./build/target/darwin/amd64/circleci-cli diagnostic
 
 Please enter your CircleCI API token:
 OK.
@@ -51,71 +53,64 @@ Host is: https://circleci.com
 OK, got a token.
 ```
 
-## Dependencies
-
-We use `dep` for vendoring our depencencies:
-https://github.com/golang/dep
+## Running a query
 
-You can install it on MacOS:
+After you've setup the CLI, you can try executing a GraphQL query against the client.
 
-```
-$ brew install dep
-$ brew upgrade dep
-```
+Given we've written the following query in a file called `query.gql`:
 
-Or on Linux, etc:
+``` graphql
+query IntrospectionQuery {
+	__schema {
+		queryType { name }
+		mutationType { name }
+		subscriptionType { name }
+		types {
+			...FullType
+		}
+		directives {
+			name
+			description
+		}
+	}
+}
 
-```
-$ curl https://raw.githubusercontent.com/golang/dep/master/install.sh | sh
+fragment FullType on __Type {
+	kind
+	name
+	description
+	fields(includeDeprecated: true) {
+		name
+	}
+}
 ```
 
-To make sure dependencies are installed:
+You can now pipe that file to the `query` command to send it.
 
 ```
-$ dep ensure
+$ cat query.gql | ./build/target/darwin/amd64/circleci-cli query
 ```
 
-## Linting
-
-We use [`gometalinter`](github.com/alecthomas/gometalinter) for linting.
-
-You can install it via `$ make dev` or manually with:
+This should pretty-print back a JSON response from the server:
 
 ```
-$ go get -u github.com/alecthomas/gometalinter
-$ gometalinter --install
+{
+	"__schema": {
+		# ...Tons O' Schema
+	}
+}
 ```
 
-Then you can run it with `$ make lint`.
-
 ## Known Issues
 
 * ...
 
-## Doc
+## Viewing API Documentation
 
-You can view `godoc` of the cli in your browser.
+You can view the documentation for this project in your browser using `godoc`.
 
-After installing it either via `go get golang.org/x/tools/cmd/godoc` or running `make dev`.
+After installing it via `make dev`.
 
-1. Run `make doc` or `godoc -http=:6060`
+1. Run `make doc`.
 2. Access http://localhost:6060/pkg/github.com/circleci/circleci-cli/
 
-## Editor support
-
-Go has great tooling such as [`gofmt`](https://golang.org/cmd/gofmt/) and [`goimports`](https://godoc.org/golang.org/x/tools/cmd/goimports).
-
-```
-$ go get golang.org/x/tools/cmd/goimports
-```
-
-You can read about `gofmt` [here](https://blog.golang.org/go-fmt-your-code). In particular, you can set it up with [vim](https://github.com/fatih/vim-go) or [emacs](https://github.com/dominikh/go-mode.el).
-
-I've the following in my `.emacs.d/init.el`:
-
-```
-(setq gofmt-command "goimports")
-(require 'go-mode)
-(add-hook 'before-save-hook 'gofmt-before-save)
-(require 'go-rename)
-```

cmd/root.go

@@ -118,7 +118,7 @@ func createConfig() (err error) {
 		Logger.FatalOnError("", err)
 	}
 	defer func() {
-	  Logger.FatalOnError("Error closing config file", file.Close())
+		Logger.FatalOnError("Error closing config file", file.Close())
 	}()
 
 	// read flag values
@@ -139,7 +139,7 @@ func createConfig() (err error) {
 		Logger.FatalOnError("", err)
 	}
 
-	Logger.Info("Your configuration has been created in `%v`.\n", cfgPathDefault)
+	Logger.Infof("Your configuration has been created in `%v`.\n", cfgPathDefault)
 	Logger.Infoln("It can edited manually for advanced settings.")
 	return err
 }