Update README.md

Include instructions for contributing.

README.md

@@ -1,11 +1,94 @@
-# flow-typed
+<img 
+  alt="Flow Logo" 
+  src="https://raw.githubusercontent.com/jeffmo/flow-typed/update_readme/flow-typed-logo.png"
+  width="400"
+/>
 
-![The Flow logo](https://raw.githubusercontent.com/facebook/flow/gh-pages/static/flow-hero-logo.png)
+`flow-typed` is a repository of third-party 
+[library interface definitions](http://flowtype.org/docs/third-party.html) 
+for use with [Flow](http://flowtype.org/).
 
-Hi, there!
+## Huh?
 
-Things are just getting started. Above you'll find a few library definitions that are already available. We're working on documentation for contribution and useage. Please check back soon, or if you're feeling adventurous, you can jump in and follow along with us here:
+When you start a project with Flow, **you might want to use some third-party 
+libraries that were *not* written with Flow**. Flow is usually able to work it's 
+way around this, but at the unfortunate cost of typing those third-party modules 
+as `any`. As a result, Flow can't give errors if you accidentally mis-use the 
+library (nor will it be able to auto-complete the library).
 
-https://github.com/splodingsocks/flow-typed/issues/4
+To address this, **Flow supports 
+[library definitions](http://flowtype.org/docs/third-party.html)** which allow 
+you to describe the interface of a module or library separate from the 
+implementation of that module/library. 
 
-🛠  🛠  🛠  🎂
+**The `flow-typed` repo is a collection of high-quality library definitions**, 
+tests to ensure that they remain high quality, and tooling to make it as easy as 
+possible to import them into your project.
+
+## How Do I Contribute?
+
+Just send a pull request!
+
+All definitions sit under the 
+[/definitions](https://github.com/flowtype/flow-typed/tree/master/definitions) 
+folder. They all must follow the following naming format:
+
+`<NPM_PACKAGE_NAME>-v<VERSION>`/`flow-v<VERSION>`/`<NPM_PACKAGE>-v<VERSION>.js`
+
+Where `<VERSION>` is a semver version number with all of MAJOR, MINOR, and PATCH
+version numbers included. `x` is an acceptable wildcard in place of any of the 
+three version numbers, and it is also acceptable to put `>=` or `<=` in front of
+the `v` to indicate a range of versions.
+
+Example filename:
+
+`underscore-v1.x.x/flow->=v0.13.x/underscore-v1.x.x.js`
+
+This is a library definition for all "1.x.x" versions of underscore that works
+with any version of Flow >= v0.13.
+
+**We structure files this way is to enable automated testing and tooling.**
+Tests ensure that library definitions continue to work as expected and the
+`flow-typed` tooling ensures that it's as easy as possible to find and install 
+library definitions.
+
+#### Writing Tests
+
+**When you contribute a new library definition (or make a change to an existing 
+one), you should include tests with your change.**
+
+Tests are simply `test-*.js` files that sit next to the library definition 
+file. Their purpose is to exercise the defined library and ultimately produce
+zero Flow errors for each version of Flow that the libdef is specified as 
+compatible with.
+
+**Often it is useful to test that a particular usage of a library definition 
+*does* produce an error.** For this you can write some code that produces a Flow 
+error and just put `// $ExpectError` on the line above where the error is 
+produced. This will tell the test runner that an error is intentional and 
+expected on the following line.
+
+## `flow-typed` CLI
+
+The `flow-typed` npm package provides a CLI that provides several commands for
+working with this repository:
+
+##### `flow-typed validate-defs`
+
+Verifies that all files under the `/definitions/` directory are structured 
+properly. **It does not run tests**, it only asserts that file and directory 
+names match the expected conventions.
+
+##### `flow-typed run-tests [optional-pattern]`
+
+Runs *all* compatible versions of Flow over the each library definition with 
+it's tests to ensure that the tests pass as expected.
+
+Note that this command assumes that the `/definitions/` directory is correctly 
+structured. You can always verify the structure with the 
+[`flow-typed validate-defs`](#flow-typed-validate-defs) command.
+
+##### *(...coming soon...)* `flow-typed libdefs-for-pkg /path/to/package.json`
+
+Scans the specified `package.json`, looks for any compatible libdefs in the 
+`flow-typed` github repo, and prints a JSON list of URLs for each that is found.