doc(README): document getting started (#16)

* doc(README): document getting started

* Add GH OAth instruction

* Add run section in README

Makefile

@@ -235,20 +235,3 @@ check: ## Concurrently runs a whole bunch of static analysis tools
 .PHONY: run
 run: build ## runs the service locally
 	$(SERVER_BIN)
-
-.PHONY: tools
-tools: ## Installs all necessary tools
-	@echo "Installing gometalinter"
-	@go get -u github.com/alecthomas/gometalinter 
-
-	@echo "Installing ginkgo"
-	@go get -u github.com/onsi/ginkgo/ginkgo
-
-	@echo "Installing gock"
-	@go get -u gopkg.in/h2non/gock.v1
-
-	@echo "Installing goimports"
-	@go get -u golang.org/x/tools/cmd/goimports
-
-	@echo "Installing goa"
-	@go get -u github.com/goadesign/goa

README.adoc

@@ -1,40 +1,61 @@
 = Build Tool Detector
-:test: gometaliner
+Little service which will detect what build tool you are using.
 
-Little service which will detect what build tool you are using
+=== Build [[build]]
 
-=== Start hacking [[hacking]]
-Use `config-template.yml` as a template to create your own `config.yml` file with the appropriate environment variable values. The application will not run unless a github client id and github client secret are provided.
-
-Use `setup.sh` script we ship in this repository to get started right away! Simply run following `curl` command to get
-latest and the greatest setup.
+==== Pre-requisites
+* link:https://golang.org/doc/install[Golang prerequisites] and `$GOPATH` setup.
+NOTE: Stick to Golang version 10 because of link:https://github.com/goadesign/goa/pull/1548[goa and golang 11]. Have a look how link:https://github.com/moovweb/gvm[Go Version Manager] can help you simplifying configuration and management of different versions of Go.
 
+* clone the repo in your GOPATH:
 [source,bash]
 ----
-$ curl -sSL https://git.io/fAPbw | bash
+$ git clone https://github.com/fabric8-services/build-tool-detector $GOPATH/src/github.com/fabric8-services/build-tool-detector
 ----
+==== Setup
+* Use `config-template.yml` as a template to create your own `config.yml` file with the appropriate environment variable values.
+[source,bash]
+----
+$ cp config-template.yml config.yml
+----
+* You need to configure GH OAuth app to test it locally:
 
-Assuming that you have all the link:https://golang.org/doc/install[Golang prerequisites] in place (such as `$GOPATH`), clone the repository first.
-
-NOTE: Have a look how link:https://github.com/moovweb/gvm[Go Version Manager] can help you simplifying configuration and management of different versions of Go.
+1. Go to https://github.com/settings/applications/new[OAuth app]
+1. Create a new developer application, in the `Authorization callback URL`,
+1. Enter the url `http://localhost:8099`.
 
-Then run the build by simply executing `make` from the root directory. This will perform following actions:
+You'll get a page with `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` that you should use in your `config.xml`:
+```
+github:
+    clientID: "GITHUB_CLIENT_ID"
+    clientSecret: "GITHUB_CLIENT_SECRET"
+```
+==== Build
 
-. Clean artifacts from the previous build
-. Fetch or update dependencies using `godep`
-. Compile and build binaries
-. Run tests
-. Run static code analysis
+[source,bash]
+----
+$ make build
+----
 
+This will perform following actions: fetch dependencies, generate Goa files from design folder, compile.
 When in doubt just `make help`.
 
-=== Continuous Testing [[testing]]
+=== Test [[test]]
 
 In order to continuously run the tests whenever code change occur execute following command from the root directory of the project:
 
 [source,bash]
 ----
-$ ginkgo watch -r
+$ make test
 ----
 
 and keep it running in the terminal.
+
+=== Run [[run]]
+
+Run the server:
+
+[source,bash]
+----
+$ make run
+----

main.go

@@ -1,4 +1,3 @@
-//go:generate goagen bootstrap -d github.com/fabric8-services/build-tool-detector/design
 
 package main