Merge pull request #7 from cloudflare/doc-updates

Doc updates

CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing to unsee
+
+## Getting Started
+
+To get started follow `Building from source` section of the `README.md` file.
+
+## Testing changes
+
+To run included tests and check code style with `golint` run:
+
+    make test
+
+## Vendoring dependencies
+
+If you use any new dependency or remove any existing one, please run:
+
+    make vendor
+
+This will install and run [manul](https://github.com/kovetskiy/manul), which
+will detect all used package and add/remove git submodule pointers in the
+vendor directory.
+
+To update all vendor package run:
+
+    make vendor-update
+
+To update specific vendor package run manul manually:
+
+    manul -Urt <package>
+
+## Running
+
+To build and start `unsee` from local branch see `Running` section of the
+`README.md` file.
+
+When working with assets (templates, stylesheets and javascript files) `DEBUG`
+flag for make can be set, which will recompile binary assets in debug mode,
+meaning that files from disk will be read instead of compiled in assets.
+See [go-bindata docs](https://github.com/jteeuwen/go-bindata#debug-vs-release-builds)
+for details. Example:
+
+    make DEBUG=true run

Makefile

@@ -21,6 +21,7 @@ endif
 	git submodule update --init --recursive
 	go get -u github.com/jteeuwen/go-bindata/...
 	go get -u github.com/elazarl/go-bindata-assetfs/...
+	go get -u github.com/golang/lint/golint
 	mkdir -p .build
 	touch $@
 
@@ -35,9 +36,13 @@ bindata_assetfs.go: .build/deps.ok .build/bindata_assetfs.$(GO_BINDATA_MODE) $(A
 $(NAME): .build/deps.ok bindata_assetfs.go $(SOURCES)
 	go build -ldflags "-X main.version=$(VERSION)"
 
+.PHONY: clean
+clean:
+	rm -fr .build $(NAME)
+
 .PHONY: run
 run: $(NAME)
-	DEBUG=true ALERTMANAGER_URI=$(ALERTMANAGER_URI) PORT=$(PORT) ./unsee
+	DEBUG=true ALERTMANAGER_URI=$(ALERTMANAGER_URI) PORT=$(PORT) ./$(NAME)
 
 .PHONY: docker-image
 docker-image: bindata_assetfs.go
@@ -61,6 +66,20 @@ lint: .build/deps.ok
 test: lint bindata_assetfs.go
 	@go test -cover `go list ./... | grep -v /vendor/`
 
+.build/vendor.ok:
+	go get github.com/kovetskiy/manul
+	mkdir -p .build
+	touch $@
+
+.PHONY: vendor
+vendor: .build/vendor.ok
+	manul -Crt
+	manul -Irt
+
+.PHONY: vendor-update
+vendor-update: .build/vendor.ok
+	manul -Urt
+
 #======================== asset helper targets =================================
 
 ASSETS_DIR := $(CURDIR)/assets/static/managed

README.md

@@ -9,6 +9,14 @@ to alert data, therefore safe to be accessed by wider audience.
 
 ## Building and running
 
+### Installing using the go command
+
+unsee is go installable, so the easiest way is to run:
+
+    go install github.com/cloudflare/unsee
+
+The `unsee` binary will be installed into `$GOPATH/bin` directory.
+
 ### Building from source
 
 To clone git repo and build the binary yourself run:
@@ -19,7 +27,7 @@ To clone git repo and build the binary yourself run:
 
 `unsee` binary will be compiled in project directory.
 
-### Running
+## Running
 
 `unsee` is configured via environment variables or command line flags.
 Environment variable `ALERTMANAGER_URI` or cli flag `-alertmanager.uri` is the
@@ -39,7 +47,9 @@ variables. Example:
 
     make PORT=5000 ALERTMANAGER_URI=https://alertmanager.example.com run
 
-### Build a Docker image
+## Docker
+
+### Building a Docker image
 
     make docker-image
 
@@ -54,7 +64,7 @@ apply as with `make run`. Example:
 
     make PORT=5000 ALERTMANAGER_URI=https://alertmanager.example.com run-docker
 
-### Environment variables
+## Environment variables
 
 #### ALERTMANAGER_TIMEOUT