Added getting started info

GoBasics.md

@@ -0,0 +1,27 @@
+# Go Basics
+
+This document is designed for developers new to the go language, especially experiecned developers who are learning go for the purpose of using tendermint.
+
+Go is a rather simple language, which aims to produce for fast, maintainable programs, while minimizing development effort.  In order to speed up development, the go community has adopted quite a number of conventions, which are used in almost every open source project. The same way one rails dev can learn a new project quickly as they all have the same enforced layout, programming following these conventions allows interoperability with much of the go tooling, and a much more fluid development experience.
+
+First of all, you should read through [Effective Go](https://golang.org/doc/effective_go.html) to get a feel for the language and the constructs. And maybe pick up a book, read a tutorial, or do what you feel best to feel comfortable with the syntax.
+
+Second, you need to set up your go environment.  In go, all code hangs out GOPATH.  You don't have a separate root directory for each project. Pick a nice locations (like `$HOME/go`) and `export GOPATH` in your startup scripts (`.bashrc` or the like). Now, when you run `go get github.com/tendermint/basecoin`, this will create the directory `$GOPATH/src/github.com/tendermint/basecoin`, checkout the master branch with git, and try to compile if there are any scripts.  All your repos will fit under GOPATH with a similar logic.  Just pick good names for your github repos. If you put your code outside of GOPATH/src or have a path other than the url of the repo, you can expect errors.  There are ways to do this, but quite complex and not worth the bother.
+
+Third, every repo in `$GOPATH/src` is checkout out of a version control system (commonly git), and you can go into those directories and manipulate them like any git repo (`git checkout develop`, `git pull`, `git remote set-url origin $MY_FORK`).  `go get -u $REPO` is a nice convenience to do a `git pull` on the master branch and recompile if needed.  If you work on develop, get used to using the git commands directly in these repos.
+
+Fourth, installing a go program is rather easy if you know what to do.  First to note is all programs compiles with `go install` end up in `$GOPATH/bin`, you probably want a line like `export PATH=$PATH:$GOPATH/bin` in your startup scripts. `go get` will checkout the repo, then try to `go install` it. Many repos are mainly a library that also export (one or more) commands, in these cases there is a subdir called `cmd`, with a different subdir for each command, using the command name as the directory name.  To compile these commands, you can go something like `go install github.com/tendermint/basecoin/cmd/basecoin` or to compile all the commands `go install github.com/tendermint/basecoin/cmd/...` (... is a go tooling shortcut for all subdirs, like `*`).
+
+Fifth, there is not good dependency management built into go, if I import another repo, I just compile against the latest master branch, or whichever version you have checked out.  This can cause serious issues, and there is tooling to do dependency management.  As of go 1.6, the `vendor` directory is standard and a copy of a repo will be used rather than the repo under GOPATH.  In order to create and maintain the code in the vendor directory, various tools have been created, with [glide](https://github.com/Masterminds/glide) being popular and in use in all the tendermint repos. In this case, `go install` is not enough.  If you are working on code from the tendermint, you will usually want to do:
+
+```
+go get github.com/tendermint/$REPO
+cd $GOPATH/src/github.com/tendermint/$REPO
+make get_vendor_deps
+make install
+make test
+```
+
+`make get_vendor_deps` should update the vendor directory using glide, `make install` will compile all commands.  `make test` is good to run the test suite and make sure things are working with your environment... failing tests are much easier to debug than a malfunctioning program.
+
+Okay, that's it, with this info you should be able to follow along and trouble-shoot any issues you have with the rest of the guide.

README.md

@@ -1 +1,74 @@
-NOTE: Basecoin is a toy project.  Basecoin is not associated with Coinbase.com, an excellent Bitcoin/Ethereum service.
+# Basecoin
+
+DISCLAIMER: Basecoin is not associated with Coinbase.com, an excellent Bitcoin/Ethereum service.
+
+Basecoin is a sample [ABCI application](https://github.com/tendermint/abci) designed to be used with the [tendermint consensus engine](https://tendermint.com/) to form a Proof-of-Stake cryptocurrency. This project has two main purposes:
+
+  1. As an example for anyone wishing to build a custom application using tendermint.
+  2. As a framework for anyone wishing to build a tendermint-based currency, extensible using the plugin system.
+
+## Contents
+
+  1. [Installation](#installation)
+  1. [(Advice for go novices)](./GoBasics.md)
+  1. [Using the plugin system](#plugins)
+  1. [Forking the codebase](#forking)
+  1. [Tutorials and other reading](#tutorials)
+
+## Installation
+
+We use glide for dependency management.  The prefered way of compiling from source is the following:
+
+```
+go get github.com/tendermint/basecoin
+cd $GOPATH/src/github.com/tendermint/basecoin
+make get_vendor_deps
+make install
+```
+
+This will create the `basecoin` binary.
+
+## Plugins
+
+Basecoin handles public-key authentication of transaction, maintaining the balance of arbitrary types of currency (BTC, ATOM, ETH, MYCOIN, ...), sending currency (one-to-one or n-to-n multisig), and providing merkle-proofs of the state. These are common factors that many people wish to have in a crypto-currency system, so instead of trying to start from scratch, you can take advantage of the basecoin plugin system.
+
+The Plugin interface is defined in `types/plugin.go`:
+
+```
+type Plugin interface {
+  Name() string
+  SetOption(store KVStore, key string, value string) (log string)
+  RunTx(store KVStore, ctx CallContext, txBytes []byte) (res abci.Result)
+  InitChain(store KVStore, vals []*abci.Validator)
+  BeginBlock(store KVStore, height uint64)
+  EndBlock(store KVStore, height uint64) []*abci.Validator
+}
+```
+
+`RunTx` is where you can handle any special transactions directed to your application. To see a very simple implementation, look at the demo [counter plugin](./plugins/counter/counter.go). If you want to create your own currency using a plugin, you don't have to fork basecoin at all.  Just make your own repo, add the implementation of your custom plugin, and then build your own main script that instatiates BaseCoin and registers your plugin.
+
+An example is worth a 1000 words, so please take a look [at this example](https://github.com/tendermint/basecoin/blob/abci_proof/cmd/paytovote/main.go#L25-L31), in a dev branch for now.  You can use the same technique in your own repo.
+
+There are a lot of changes on the dev branch, which should be merged in my early February, so experiment, but things will change soon....
+
+## Forking
+
+If you do want to fork basecoin, we would be happy if this was done in a public repo and any enhancements made as PRs on github.  However, this is under the Apache license and you are free to keep the code private if you wish.
+
+If you don't have much experience forking in go, there are a few tricks you want to keep in mind to avoid headaches. Basically, all imports in go are absolute from GOPATH, so if you fork a repo with more than one directory, and you put it under github.com/MYNAME/repo, all the code will start caling github.com/ORIGINAL/repo, which is very confusing.  My prefered solution to this is as follows:
+
+  * Create your own fork on github, using the fork button.
+  * Go to the original repo checked out locally (from `go get`)
+  * `git remote rename origin upstream`
+  * `git remote add origin git@github.com:YOUR-NAME/basecoin.git`
+  * `git push -u origin master`
+  * You can now push all changes to your fork and all code compiles, all other code referencing the original repo, now references your fork.
+  * If you want to pull in updates from the original repo:
+    * `git fetch upstream`
+    * `git rebase upstream/master` (or whatever branch you want)
+
+## Tutorials
+
+We are working on some tutorials that will show you how to set up the genesis block, build a plugin to add custom logic, deploy to a tendermint testnet, and connect a UI to your blockchain.  They should be published during the course of February 2017, so stay tuned....
+
+