Merge pull request #417 from silvin-lubecki/experimental-readme

Move experimental building part to BUILDING.md

BUILDING.md

@@ -30,7 +30,7 @@ end you need to have `GOPATH` set in your environment.
 
 At this point you can use `go` to checkout `docker-app` in your `GOPATH`:
 
-```sh
+```console
 go get github.com/docker/app
 ```
 
@@ -39,14 +39,14 @@ You are ready to build `docker-app` yourself!
 `docker-app` uses `make` to create a repeatable build flow. It means that you
 can run:
 
-```sh
+```console
 make
 ```
 
 This is going to build all the project binaries in the `./bin/`
 directory, run tests (unit and end-to-end).
 
-```sh
+```console
 make bin/docker-app             # builds the docker-app binary
 make bin/docker-app-darwin      # builds the docker-app binary for darwin
 make bin/docker-app-windows.exe # builds the docker-app binary for windows
@@ -59,6 +59,16 @@ make test-e2e                   # run the end-to-end tests
 Vendoring of external imports uses the [`dep`](https://github.com/golang/dep) tool.
 Please refer to its documentation if you need to update a dependency.
 
+### Experimental
+
+Just add the `EXPERIMENTAL=on` flag before invoking a build target:
+```console
+$ make EXPERIMEMTAL=on bin/docker-app
+$ ./bin/docker-app version
+...
+Experimental: on
+```
+
 ## Build using Docker
 
 If you don't have Go installed but Docker is present, you can also use
@@ -89,7 +99,7 @@ capabilities without using the `Makefile` targets. The following
 examples show how to specify a test name and also how to use the flag
 directly against `go test` to run root-requiring tests.
 
-```sh
+```console
 # run the test <TEST_NAME>:
 go test -v -run "<TEST_NAME>" .
 ```

README.md

@@ -2,7 +2,6 @@
 
 An *experimental* utility to help make Compose files more reusable and sharable.
 
-
 ## The problem application packages solve
 
 Compose files do a great job of describing a set of related services. Not only are Compose files easy to write, they are generally easy to read as well. However, a couple of problems often emerge:
@@ -234,6 +233,7 @@ We have lots of ideas for making Compose-based applications easier to share and
 * Saving required images into the application artifact to support offline installation
 * Signing applications with notary
 
+If you're interested in contributing to the project, jump to [BUILDING.md](BUILDING.md) and [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Usage
 
@@ -301,11 +301,4 @@ source <(docker-app completion zsh)
 
 Some commands are flagged as experimental and will remain in this state until they mature. These commands are only accessible using an experimental binary. Feel free to test these commands and give us some feedback!
 
-### How to build your own experimental binary
-
-```console
-$ make EXPERIMEMTAL=on bin/docker-app
-$ ./bin/docker-app version
-...
-Experimental: on
-```
+See [BUILDING.md/Experimental](BUILDING.md#experimental).