diff --git a/README.md b/README.md
index 4149335887dc9bb6e7b221fe950b722ffd181f17..fbf2a687b763b88df249b06553e2b658dba07377 100644
--- a/README.md
+++ b/README.md
@@ -2,11 +2,11 @@
- License, v. 2.0. If a copy of the MPL was not distributed with this
- file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
-Here lives the [BrowserID][] implementation. BrowserID is an implementation of the
-[verified email protocol][VEP].
+Here lives the [Persona][] login implementation. This is an implementation of the
+[BrowserID protocol][].
- [BrowserID]:https://login.persona.org
- [VEP]:https://wiki.mozilla.org/Labs/Identity/VerifiedEmailProtocol
+ [Persona]: https://browserid.org
+ [BrowserID protocol]: https://github.com/mozilla/id-specs
This repository contains several distinct things related to BrowserID:
@@ -16,33 +16,58 @@ This repository contains several distinct things related to BrowserID:
* **the login.persona.org website** - the templates, css, and javascript that make up the visible part of login.persona.org
* **the javascript/HTML dialog & include library** - this is include.js and the code that it includes, the bit that someone using browserid will include.
-## Dependencies
+## Getting Started
-Here's the software you'll need installed:
+If you want to work on the core BrowserID service, follow these instructions:
-* node.js (>= 0.6.2): http://nodejs.org/
+### Install Dependencies
+
+BrowserID needs the following dependencies before it can run:
+
+* node.js (>= 0.6.2): http://nodejs.org
* npm: http://npmjs.org/ (or bundled with node in 0.6.3+)
* libgmp3
* git
* g++
-## Getting started:
+For detailed instructions for your particular operating system, check out the `SETUP` docs in the `docs/` folder.
+
+### Configure Git
+
+The BrowserID team uses Git and GitHub for all of our collaboration, code hosting, and bug tracking. If you want to help out with core development, you'll need to sign up for a GitHub account and configure Git:
+
+1. Sign up for a GitHub account at https://github.com/
+2. Learn how to configure Git at http://help.github.com/articles/set-up-git
+3. Learn how to fork and clone a repository at https://help.github.com/articles/fork-a-repo
+
+If you'd like to use SSH keys instead of a password when you authenticate with GitHub, refer to https://help.github.com/articles/generating-ssh-keys
+
+If you'd like to contribute code back to us, please do so using a GitHub Pull Request, as we follow the "Fork and Pull" collaborative development model. You can learn about pull requests at https://help.github.com/articles/using-pull-requests
+
+### Running BrowserID Locally
+
+To run the BrowserID service locally, you must first:
+
+1. Clone the repository to your local machine.
+2. Run `npm install` from the root of your local clone.
+
+You can then start the BrowserID suite of services by running `npm start` from the root of your local clone.
+
+When you run `npm start`, it will print several URLs to your terminal. You can test that everything is working by visiting the URL for the `example` (RP) site. Look for a line like this in the terminal: `example (10361): running on http://127.0.0.1:10001`.
-1. install node and npm
-3. run `npm install` to install 3rd party libraries and generate keys
-3. run `npm start` to start the servers locally
-4. visit the demo application ('rp') in your web browser (url output on the console at runtime)
+You can stop the services by typing Control-C in the terminal.
-You can stop the servers with a Cntl-C in the terminal.
+### Staying Up to Date
-## Staying up to date:
+To stay up to date with BrowserID:
-1. `rm -Rf var node_modules`
-2. `npm install`
+1. Use `git pull` to retrieve new changes.
+2. Delete both the `var` and `node_modules` folders in the root of your local clone.
+3. Run `npm install` from the root of your local clone.
## Testing
-### Local Testing
+### Local testing:
Unit tests can be run by invoking `npm test` at the top level. At present,
there are three classes of unit tests to be run:
@@ -53,7 +78,7 @@ there are three classes of unit tests to be run:
You can control which tests are run using the `WHAT_TESTS` env var, see
`scripts/test` for details.
-### Continuous Integration Testing
+### Continuous Integration Testing:
Integration tests are done with [Travis-CI][]. It is recommended that you setup [Travis-CI][] for your BrowserID fork so that tests are automatically run when you push changes. This will give the BrowserID team confidence that your changes both function correctly and do not cause regressions in other parts of the code. Configuration files are already included in the repo but some setup is necessary.
1. Sign in to [GitHub][]
@@ -71,7 +96,7 @@ Integration tests are done with [Travis-CI][]. It is recommended that you setup
[Travis-CI]: http://travis-ci.org
[GitHub]: https://github.com
-## Development model
+## Development Model
**branching & release model** - You'll notice some funky branching conventions, like the default branch is named `dev` rather than `master` as you might expect. We're using gitflow: the approach is described in a [blog post](http://lloyd.io/applying-gitflow).
diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md
index b4425f6553fb6c22bff20c39a27401ff5eec5c19..0884334dd5b8d87388bc8b3cce17a3dda0d0a3e1 100644
--- a/docs/DEPLOYMENT.md
+++ b/docs/DEPLOYMENT.md
@@ -75,7 +75,7 @@ Let's get started:
2. install git if required: `sudo apt-get install git-core`
3. become user git: `sudo su -s /bin/bash git`
4. hop into your home directory: `cd`
- 5. install gitolite: [This.](http://sitaramc.github.com/gitolite/nonroot.html)
+ 5. install gitolite: [This.](https://github.com/sitaramc/gitolite)
6. add a browserid repo: [This.](http://sitaramc.github.com/gitolite/add.html)
At this point you've morphed your servers into git servers. Go ahead and
diff --git a/docs/ORGANIZATION.md b/docs/ORGANIZATION.md
index 785f00b36671f4f0921fdcf4132f5a5474971146..fbb4aca2a4b16ccbe6a6aeaa4bc2ea3cd61411a5 100644
--- a/docs/ORGANIZATION.md
+++ b/docs/ORGANIZATION.md
@@ -43,4 +43,4 @@ and they share the following directory structure:
* `tests/` - Tests written using [vows](http://vowsjs.org)
- * Run via `scripts/run_all_tests.sh`
+ * Run via `scripts/test`
diff --git a/docs/SETUP_UBUNTU.md b/docs/SETUP_UBUNTU.md
new file mode 100644
index 0000000000000000000000000000000000000000..7f13367da2184c61fc6124dc56403428363d7283
--- /dev/null
+++ b/docs/SETUP_UBUNTU.md
@@ -0,0 +1,9 @@
+Installing Dependencies on Ubuntu
+---------------------------------
+
+Run the following to install necessary dependencies:
+
+ sudo apt-add-repository ppa:chris-lea/node.js
+ sudo apt-get update
+ sudo apt-get install python-software-properties
+ sudo apt-get install nodejs npm git-core libgmp3-dev g++