Add a README describing how to contribute to pub.

sdk/lib/_internal/pub/README.md

Index: sdk/lib/_internal/pub/README.md
diff --git a/sdk/lib/_internal/pub/README.md b/sdk/lib/_internal/pub/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..3d5a3b123f96490bcf0645a2f3b2e274a26dd482
--- /dev/null
+++ b/sdk/lib/_internal/pub/README.md
@@ -0,0 +1,67 @@
+# Working on pub

[Bob Nystrom, 2013/11/15 00:14:03]

"Contributing to pub"? "Working" sounds like... work. :)

Before we get people to run off and start coding, it might be good to suggest
that they get in touch first and tell us what they're interested in working on.
It would suck if they spent a bunch of time on something that we were working on
too.

[nweiz, 2013/11/15 01:30:44]

Done.
Done.

+
+We love contributions to pub from outside the core team, but the codebase is
+large and can be hard to understand. This document is intended to get

[Bob Nystrom, 2013/11/15 00:14:03]

The "but" is a bit negative here. How about:

Thanks for being interested in contributing to pub! Contributing to a new
project can be hard: there's a lot of new code and practices to learn. This
document...

[nweiz, 2013/11/15 01:30:44]

Done.

+contributors up and running as quickly as possible. If you're looking for
+documentation on using pub, try [pub.dartlang.org](http://pub.dartlang.org/doc).
+
+## Organization
+
+Pub isn't a package, but it's organized like one. It has four top-level
+directories:
+
+* `lib/` contains the implementation of pub. Currently, it's all in `lib/src/`,
+  since there are no libraries intended for public consumption.
+
+* `test/` contains the tests for pub.
+
+* `bin/` contains `pub.dart`, the entrypoint script that's run whenever a user
+  types "pub" on the command line or runs it in the Dart editor.

[Bob Nystrom, 2013/11/15 00:14:03]

May also want to mention the actual shell scripts in sdk/bin here too.

[nweiz, 2013/11/15 01:30:44]

Done.

+
+* `resource/` contains static resource files that pub uses. They're
+  automatically distributed in the Dart SDK.
+
+It's probably easiest to start diving into the codebase by looking at a
+particular pub command. All the commands are encapsulated in files in

[Bob Nystrom, 2013/11/15 00:14:03]

I think this reads better singular: "Each command is encapsulated in a file
in..."

[nweiz, 2013/11/15 01:30:44]

Done.

+`lib/src/command/`.
+
+## Running pub
+
+To run pub from the Dart repository, first build Dart. From the root of the

[Bob Nystrom, 2013/11/15 00:14:03]

Link to the page for building the SDK for more details here, especially the
initial setup.

[nweiz, 2013/11/15 01:30:44]

Done.

+repo:
+
+    ./tools/build.py -m release
+
+You'll need to re-build whenever you sync the repository, but not when you
+modify pub or any packages it depends on. To run pub, just run `sdk/bin/pub` (or
+`sdk/bin/pub.bat` on Windows).
+
+## Testing pub
+
+Before any change is made to pub, all tests should pass. To run all the pub
+tests, run this from the root of the Dart repository:
+
+    ./tools/test.py -m release pub
+
+Most changes to pub should be accompanied by one or more tests that exercises

[Bob Nystrom, 2013/11/15 00:14:03]

"Most changes" -> "Changes". Exceptions are rare. :)
Also "exercises" -> "exercise".

[nweiz, 2013/11/15 01:30:44]

Done.

+the new functionality. When adding a test, the best strategy is to find a
+similar test in `test/` and follow the same patterns. Note that pub makes wide
+use of the [scheduled_test] package in its tests, so it's usually important to be

[Bob Nystrom, 2013/11/15 00:14:03]

Long line.

[nweiz, 2013/11/15 01:30:44]

Done.

+familiar with that when adding tests.
+
+[scheduled_test]: http://pub.dartlang.org/packages/scheduled_test
+
+Pub tests come in two basic forms. The first, which is usually used to unit test
+classes and libraries internal to pub, has many tests in a single file. This is
+used when each test will take a short time to run.

[Bob Nystrom, 2013/11/15 00:14:03]

Give an example here like version_test.

[nweiz, 2013/11/15 01:30:44]

Done.

+
+The other form is usually used for integration tests of user-visible pub
+commands. Each test has a file to itself, which is named after the test

[Bob Nystrom, 2013/11/15 00:14:03]

Mention most tests are of this form.

[nweiz, 2013/11/15 01:30:44]

Done.

+description. This is used when tests can take a long time to run to avoid having
+the tests time out when running on the build bots.

[Bob Nystrom, 2013/11/15 00:14:03]

Give an example.

[nweiz, 2013/11/15 01:30:44]

Done.

+
+When testing new functionality, it's often useful to run a single test rather
+than the entire test suite. You can do this by appending the path to the test
+file to the test command. For example, to run `get/relative_symlink_test.dart`:
+
+    ./tools/test.py -m release pub/get/relative_symlink_test

[Bob Nystrom, 2013/11/15 00:14:03]

How about a short section at the end for getting your patch landed? You can
mostly just link to the contributor guide, but that makes sure this doc covers
the full workflow.

[nweiz, 2013/11/15 01:30:44]

Done.