Merge pull request #274 from cosmos/jordan/readme

readme improvements

README.md

@@ -1,137 +1,133 @@
-# cosmos-ui
+![the cosmos network](cosmos-github.jpg)
 
-> Human interface to Cosmos. Links to binary downloads coming soon.
+# Cosmos UI
 
-## Warning
+👋 Welcome to the official user interface for the [Cosmos Network](https://cosmos.network/).
 
-This is still alpha-level software as of September 2017. Do not enter in your Cosmos fundraiser seed.
+💻 The Cosmos UI is a desktop application built with [Electron](https://github.com/electron/electron). Cosmos UI runs on macOS 10.9+, Windows 7+, and Debian-based Linux distros.
 
-## Development
+⚠️ This is still alpha-level software. __DO NOT__ enter your Cosmos fundraiser seed into the UI.
 
-To run the dev build, you will need the `gaia` binary installed:
-```golang
+🎉 Releases can be found [here](https://github.com/cosmos/cosmos-ui/releases).
+
+---
+
+### Prerequisites
+
+`gaia` is a prepackaged version of Cosmos SDK and Tendermint. You will need `gaia` installed.
+
+```bash
+# install go, set $GOPATH
+brew install go
+
+# install glide
+brew install glide
+
+# install gaia
 go get github.com/cosmos/gaia
 cd $GOPATH/src/github.com/cosmos/gaia
 git checkout develop
 glide install
 make install
 ```
 
-To run on the default testnet
-```bash
-$ npm run testnet
-```
+You will also need `yarn` to install node modules:
 
-OR, specify a testnet from the github.com/tendermint/testnets repo
 ```bash
-$ npm run testnet <networkName>
-```
+brew install yarn
 
-If you want to see the UI and work on that only, you can use:
-```bash
-$ yarn run uionly
+# in the project folder, run
+yarn
 ```
-This will not start the blockchain conenction.
 
-## Production
+---
 
-You can create production builds to get an app which will connect to an actual blockchain network.
+### Develop
 
-First you will need the prerequisite source repositories installed:
+To run on the UI on the default testnet (`gaia-2-dev`):
+```bash
+$ yarn run testnet
+```
 
+To run the UI on a specific a testnet from the [testnets](https://github.com/tendermint/testnets) repo:
 ```bash
-# install go, set $GOPATH
-brew install go
+$ yarn run testnet <networkName>
+```
 
-# install glide
-brew install glide
+To run the UI with a mocked backend (without connecting to a testnet):
+```bash
+$ yarn run uionly
+```
 
-# install basecoin/baseserver
-go get -d github.com/cosmos/cosmos-sdk
-cd $GOPATH/src/github.com/cosmos/cosmos-sdk // Windows: cd %GOPATH%/src/github.com/cosmos/cosmos-sdk
-git checkout develop
-make get_vendor_deps
-make install
+---
 
-# install tendermint
-go get -d github.com/tendermint/tendermint/cmd/tendermint
-cd $GOPATH/src/github.com/tendermint/tendermint // Windows: cd %GOPATH%/src/github.com/tendermint/tendermint
-git checkout v0.11.0
-make get_vendor_deps
-make install
-```
+### Production
 
-Then build and run the app:
+Build and run the app.
 ```bash
 npm run pack && npm run build:darwin
 open builds/Cosmos-darwin-x64/Cosmos.app
 ```
 
-When you are testing the build system you can skip the repackaging of the JS files with:
+When you are testing the build system you can skip the repackaging of the JS files.
 ```bash
 $ npm run build -- --skip-pack
 ```
 
+---
+
 ### Build on Windows
 
 - Install [golang](`https://golang.org/dl/`)
 - Install [glide](`https://github.com/Masterminds/glide/releases`)
-
 - Install [node](`https://nodejs.org/en/download/`)
 - Install Yarn: `$ npm i -g yarn`
 - Install Microsoft build tools: `$ npm install --global --production windows-build-tools`
 - Set build tools to needed version `yarn config set msvs_version 2015 --global`
-
 - Install [GNU MAKE](`http://gnuwin32.sourceforge.net/packages/make.htm`)
 - Install [MinGW64](`https://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win32/Personal%20Builds/mingw-builds/installer/mingw-w64-install.exe/download`)
 - Add MAKE and MinGW64 to the PATH environment variable ([HOW TO](https://msdn.microsoft.com/de-de/library/windows/desktop/bb776899(v=vs.85).aspx))
     - MAKE should be at `C:\Program Files (x86)\GnuWin32\bin`
     - MinGW64 you have to look up at `C:\Program Files\mingw-w64\{{version}}\mingw64\bin`
-
 - Pack the electron application: `$ npm run build:win32`
 - Build the Setup: `$ npm run release:win32`
 - The installer will be under `./builds/cosmos/Cosmos-win32`
 
-## Testing
+---
+
+### Testing
 
-To test you need to first package the web content of the app, as this content can only be used bundled by the electron instance.
+The UI is using [Jest](https://facebook.github.io/jest) to run unit tests.
 
 ```bash
-$ npm run pack
-$ npm run test
+$ yarn run test
 ```
 
-To see where you are missing coverage, run a test first and then open an http-server at `test/unit/coverage/lcov-report` to see details for the coverage.
+To check test coverage, run the command above and then open an http-server at `test/unit/coverage/lcov-report` to see details for the coverage.
 i.e.:
 
 ```bash
 $ npm i -g http-server
 $ http-server test/unit/coverage/lcov-report
 ```
 
-To test the running application e2e:
-
-```bash
-$ npm run pack
-$ npm run test:e2e
-```
+---
 
-## Debug
+### Debug
 
-To debug the electron application first build it and then run the node inspector for the build files:
+To debug the electron application, build it and run the node inspector for the built files:
 
 ```bash
 $ electron --inspect-brk builds/{{your build}}/resources/app/dist/main.js
 ```
 
 Then attach to the debugger via the posted url in Chrome.
 
-
 To debug the electron view, set the environment variable `COSMOS_DEVTOOLS` to something truthy like `"true"`.
 
 To see the console output of the view in your terminal, set the environment variable `ELECTRON_ENABLE_LOGGING` to something truthy like `1`.
 
-## Flags
+### Flags
 
 A list of all environment variables and their purpose:
 
@@ -150,30 +146,33 @@ A list of all environment variables and their purpose:
 |PREVIEW|'true', 'false'|'true' if NODE_ENV 'development'|Show/Hide features that are in development|
 
 
-## FAQ
+### FAQ
 
-- If tendermint crashes and the log shows "Tendermint state.AppHash does not match AppHash after replay." delete the config folders at $HOME/.cosmos-ui[-dev].
+- If tendermint crashes and the log shows `Tendermint state.AppHash does not match AppHash after replay.` delete the config folders at `$HOME/.cosmos-ui[-dev]`.
 
-- If you use yarn, the postinstall hook may not execute. In this case you have to execute these script manualy:
+- If you use yarn, the post-install hook may not execute. If this happens you'll have to execute the script manually:
 ```bash
 $ cd app
 $ yarn
 $ cd ..
 $ npm run rebuild
 ```
 
-- If electron shows the error: "A DLL initialization routine has failed." rebuild the electron dependencies.
+- If electron shows the error: `A DLL initialization routine has failed.` rebuild the electron dependencies:
 ```bash
 $ npm run rebuild
 ```
 
-- If you have trouble installing dependencies, remove all the lockfiles and try again.
-
+- If you have trouble installing dependencies, remove all the lockfiles and try installing again.
 ```bash
 $ rm -rf app/yarn.lock
 $ rm -rf app/package-lock.json
 $ rm -rf yarn.lock
 $ rm -rf package-lock.json
 ```
 
-- If your components are not found using a short path, check if the path resolution is applied for webpack (in `webpack.renderer.js > rendererConfig.resolve.alias`) and jest (in `package.json > jest.moduleNameMapper`).
+- If your components are not found using a short path, check if the path resolution is applied for Webpack (`webpack.renderer.js > rendererConfig.resolve.alias`) and Jest (`package.json > jest.moduleNameMapper`).
+
+---
+
+### ✌️