1
0
Fork 0
mirror of https://we.phorge.it/source/phorge.git synced 2024-11-14 19:02:41 +01:00
Commit graph

120 commits

Author SHA1 Message Date
epriestley
de0c89261e Allow Maniphest tasks to be filtered by Project
Summary:
Major things taking place here:

  - A new table for storing <task, project> relationships.
  - Moved all task query logic into a dedicated class.
  - Added a "projects" filter to the UI.

I was originally going to try to drive this off the main search index but the
perf benefits of a custom schema make an overwhelming argument in favor of doing
it this way.

Test Plan:
Filtered tasks by author and owner and zero, one, and more than one project.
Exercised all the group/sort options. Ran the index script over my 100k task
corpus. Edited task-project membership and verified the index updated.

Reviewed By: cadamo
Reviewers: gc3, jungejason, cadamo, tuomaspelkonen, aran
CC: aran, cadamo, epriestley
Differential Revision: 556
2011-06-29 21:56:47 -07:00
epriestley
4469ef8f30 Allow Maniphest to scale to a massive size
Summary:
Maniphest is missing some keys and some query strategy which will make it
cumbersome to manage more than a few tens of thousands of tasks.

Test Plan:
Handily manipulated 100k-scale task groups. Maniphest takes about 250ms to
select and render pages of 1,000 tasks and has no problem paging and filtering
them, etc. We should be good to scale to multiple millions of tasks with these
changes.

Reviewed By: gc3
Reviewers: fratrik, jungejason, aran, tuomaspelkonen, gc3
Commenters: jungejason
CC: anjali, aran, epriestley, gc3, jungejason
Differential Revision: 534
2011-06-28 06:41:05 -07:00
epriestley
e0e6ec9117 Allow affiliations to carry project ownership information; transform profile
images correctly

Summary:
This is sort of doing two things at once:

  - Add an "isOwner" flag to Project Affiliation to lay the groundwork for T237.
  - Rename the "QuickCreate" workflow to "Create" and funnel all creation
through it.
  - Reorganize the image transformation stuff and use it to correctly
crop/resize uploaded images.

Test Plan:
Created and edited projects and affailiations. Uploaded project, user, and
profile photos. Verified existing thumbnailing in Maniphest still works
properly.

Reviewed By: cadamo
Reviewers: cadamo, aran, jungejason, tuomaspelkonen
CC: aran, epriestley, cadamo
Differential Revision: 529
2011-06-28 06:40:41 -07:00
epriestley
46a7676a6a Properly scope some SQL. 2011-06-21 14:46:59 -07:00
epriestley
431c57688e Improve performance of project list view
Summary:
D477 added functionality to the project list view but had a couple of
performance issues that I missed in review, because it took the query count for
the page from around 3 to as many as 300, including up to 100 heavyweight search
index queries.

This fixes the two simple N+1 query problems. This general pattern of data
access often occurs:

  COUNTEREXAMPLE
  $cats = load_cats();
  foreach ($cats as $cat) {
    $cats_hats = load_hats_for_cat($cat);
    // ...
  }

But this issues "N+1" queries, i.e. if you load 100 cats you issue 101 queries.
It is faster to group the queries instead:

  $cats = load_cats();
  $hats = load_all_hats_for_these_cats($cats);
  foreach ($cats as $cat) {
    $cats_hats = $hats[$cat->getID()];
  }

MySQL can execute one query which returns all the results much faster than 100
queries which return one result, especially if the database is not local (i.e.,
over the network).

However, this doesn't save a ton of time. The bigger issue is that I didn't have
the right keys on the relationship tables in the search engine. This adds them,
and reduces the search engine lookup cost from 25-80ms (for
secure.phabricator.com) down to 1-3ms.

I still probably want to get this out of the loop at some point but it's okay
for now and the page loads in a few ms rather than taking more than a second.

Test Plan:
Used "services" tab, "xhprof" and "EXPLAIN" to analyze page performance. I
measured these changes:

  - Query count: 1 + (3 * N projects) -> 3 + (N projects) (e.g., 301 -> 103)
  - Total time spent querying, ignoring search indexes: 40ms (local.aprhont.com)
-> 20ms (local.aphront.com)
  - Cost for search index query: 25-80ms (secure.phabricator.com) -> 1-3ms

Reviewed By: cadamo
Reviewers: cadamo, aran, jungejason, tuomaspelkonen
CC: aran, cadamo, epriestley
Differential Revision: 485
2011-06-21 14:43:15 -07:00
epriestley
4acf457431 Merge remote branch 'cadamo/devel'
Conflicts:
	src/__celerity_resource_map__.php
2011-06-20 16:06:03 -07:00
epriestley
25bbe741f4 Provide a default non-NULL timezone in the PhabricatorUser class
Summary:
Without this, user creation throws an exception when trying to insert NULL into
a non-NULL field.

Test Plan:
Created a new user.

Reviewed By: fratrik
Reviewers: fratrik, toulouse, aran, jungejason, tuomaspelkonen
CC: aran, fratrik
Differential Revision: 480
2011-06-20 13:13:51 -07:00
Cristian Adamo
7851b6573f Project list and profile view modifications
Summary: Added some change on the project's list view, to show information about
active tasks, population, etc. Also modified the "profile view", and added a class "PhabricatorProfileView" to render the profile, both on projects and users.

Test Plan: play around the project directory :)

Reviewers: epriestley ericfrenkiel

CC:

Differential Revision: 477
2011-06-20 16:13:44 -03:00
epriestley
5915d1dbde Fix syntax clowning in patch 046. 2011-06-20 05:59:42 -07:00
epriestley
513178c7ec Deconflict SQL patches. 2011-06-20 05:58:32 -07:00
epriestley
1cd1e1ed18 "arc install-certificate", server-side components
Summary:
Provides a new workflow for making it non-horrible to install certificates.
Basically you run "arc install-certificate" and then copy/paste a short token
off a webpage and it does the ~/.arcrc edits for you.

Test Plan:
Installed certificates, used bad tokens, hit rate limiting.

Reviewed By: aran
Reviewers: aran, jungejason, tuomaspelkonen
CC: aran
Differential Revision: 460
2011-06-20 05:18:02 -07:00
Andrew Toulouse
9b522982fa Add timezone support
Summary:
Allows user-configurable timezones. Adds a preference panel, and migrates to the
new date rendering in easily-modified areas of the code. ***In progress***.

Test Plan:
Check database to make sure the field is being changed when the settings are
changed; check affected views to see how they render times.

Reviewed By: epriestley
Reviewers: epriestley
CC: aran, epriestley, toulouse
Differential Revision: 475
2011-06-18 13:07:43 -07:00
epriestley
aa86cf0ed8 Countdown tweaks
Summary:
A few tweaks to hsb's Countdown implementation:

  - Allow the page to be rendered "chromeless", suitable for display on one of
the dozens of monitors everyone has laying around.
  - Show title of countdown in deletion dialog.
  - When creating a new countdown default to time(), not Dec 31, 1969.
  - Add extra "/" after editing to avoid needless redirect.
  - Tweak some page titles.
  - Show countdown author in list view.
  - Highlight tab in list view.
  - Tweak menu copy.
  - Link countdown title in list view, separate buttons into different columns
so they pick up padding.

Test Plan:
Created, edited and deleted a timer. Viewed a timer and toggled chrome mode.
Viewed timer list.

Reviewed By: hsb
Reviewers: hsb, aran, jungejason, tuomaspelkonen
CC: aran, hsb, epriestley
Differential Revision: 454
2011-06-13 18:53:43 -07:00
Hafsteinn Baldvinsson
a11b5e8bbc Countdown
Summary:
Addon that allows you to create a live countdown page to
some event.

Here is the ticket that this code is based on
https://secure.phabricator.com/T36

Test Plan:
Tested by manually setting dates in the timer.js file and
checking if they made sense.
I'm not sure if it works across different timezones though.

Reviewers: epriestley

CC:

Differential Revision: 436
2011-06-13 02:23:46 +00:00
Ricky Elrod
b9c9f90164 Pastebin
Summary:
This is Paste. It needs some work, but epriestley recommended that I just commit something that works, and expand on that later.

Specifically, it lacks the ability to view a raw paste right now, and to turn off line numbers, making it hard to copy/paste from for now. It works for showing other people code, however.

Test Plan:
Pasted stuff, and was able to view it, and see it in the list on /paste/. Put a file extension in the title, and saw that syntax highlighting worked as expected.

Reviewers:
epriestley

CC:

Differential Revision: 424
2011-06-10 13:41:18 -04:00
epriestley
2e8990e9e0 Store metadata with Differential and Maniphest comments, and store added
reviewers as metadata

Summary:
The "Add reviewer" implementation is super lazy right now since I didn't want to
do a schema change. Man up and add a column. I also plan to store "via"
information here (e.g., via email or via mobile).

NOTE: This schema change may take a while since the comment table is pretty big
in Facebook's install.

This needs a little CSS work but I think it's reasonable for now.

Test Plan:
Made comments on revisions and tasks. Added reviewers to a revision, got linked
names instead of a blob of text.

Reviewed By: aran
Reviewers: tomo, jungejason, tuomaspelkonen, aran
Commenters: tomo
CC: aran, tomo, epriestley
Differential Revision: 394
2011-06-09 10:43:25 -07:00
gc3
22c1b38655 herald: add the ability to execute a rule the first time only
Summary:
- added a new config class for representing the kind of repetition a rule has
(once, every time, first time only)

- added an email action to herald rules for differential to allow someone to get
an email but only the first one

- changed the herald rule ui to allow a user to pick the amount of repetition

Test Plan:
created a test rule and ran it over and over

Reviewed By: epriestley
Reviewers: epriestley, tuomaspelkonen
CC: aran, epriestley, gc3
Revert Plan:
Tags:

- begin *PUBLIC* platform impact section -
Bugzilla: #
- end platform impact -

Differential Revision: 357
2011-06-09 10:35:37 -07:00
epriestley
8af5bb117d Basic image thumbnailing
Summary:
This is still very rough but provides basic support for generating image
thumbnails. I need to separate stuff out a bit but I'm going to integrate into
Maniphest before I hit the profile stuff so this seems like a reasonable
starting point.

Test Plan:
Generated some image thumbnails in various sizes.

Reviewed By: aran
Reviewers: jungejason, tuomaspelkonen, aran
CC: aran
Differential Revision: 333
2011-05-27 09:33:33 -07:00
epriestley
deb80b7652 Provide an activity log for login and administrative actions
Summary: This isn't complete, but I figured I'd ship it for review while it's still smallish.

Provide an activity log for high-level system actions (logins, admin actions). This basically allows two things to happen:

  - The log itself is useful if there are shenanigans.
  - Password login can check it and start CAPTCHA'ing users after a few failed attempts.

I'm going to change how the admin stuff works a little bit too, since right now you can make someone an agent, grab their certificate, revert them back to a normal user, and then act on their behalf over Conduit. This is a little silly, I'm going to move "agent" to the create workflow instead. I'll also add a confirm/email step to the administrative password reset flow.

Test Plan: Took various administrative and non-administrative actions, they appeared in the logs. Filtered the logs in a bunch of different ways.

Reviewers: jungejason, tuomaspelkonen, aran

CC:

Differential Revision: 302
2011-05-20 19:08:26 -07:00
epriestley
f9f8ef0e6e Admin and disabled flags for users
Summary:
Provide an "isAdmin" flag for users, to designate administrative users.

Restore the account editing interface and allow it to set role flags and reset
passwords.

Provide an "isDisabled" flag for users and shut down all system access for them.

Test Plan:
Created "admin" and "disabled" users. Did administrative things with the admin
user. Tried to do stuff with the disabled user and was rebuffed. Tried to access
administrative interfaces with a normal non-admin user and was denied.

Reviewed By: aran
Reviewers: tuomaspelkonen, jungejason, aran
CC: ccheever, aran
Differential Revision: 278
2011-05-12 11:17:50 -07:00
epriestley
f7e2b03077 Add a "setup" mode which guides new users through application configuration
Summary:
Alters the installation instructions to guide installers into a "setup" mode
which does config file sanity checking.

Test Plan:
Put myself in setup mode, simulated all the failures it detects, took myself out
of setup mode, Phabricator works OK.

Reviewed By: tuomaspelkonen
Reviewers: jungejason, tuomaspelkonen, aran
CC: aran, tuomaspelkonen, epriestley
Differential Revision: 230
2011-05-10 15:12:30 -07:00
epriestley
25dee6ecd2 Support email replies in Phabricator
Summary:
Provides support for per-user x per-object unique reply-to email addresses, plus
SMTP integration.

This does not actually make Phabricator use these in outbound email.

Test Plan:
Used test console to validate in-Phabricator routing and handling.

Piped emails into the "mail_handler.php" script to validate mail parsing.

Configured sendmail and sent mail to Phabricator.

Technically I haven't conducted all parts of this test on the same machine since
I lost the will to configure more SMTP servers after configuring phabricator.com

Reviewed By: jungejason
Reviewers: jungejason, tuomaspelkonen, aran
CC: aran, epriestley, jungejason
Differential Revision: 226
2011-05-05 14:58:57 -07:00
epriestley
03ebbccbc9 Restore image proxying to Remarkup
Summary:
Previously, Remarkup allowed you to paste in an image URI and get an inline
image. However, it did this by hotlinking the image which isn't so hot in an
open source product.

Restore this feature, but use image proxying instead. The existing image macro
code does most of the work.

There is a mild security risk depending on the network setup so I've left this
default-disabled and made a note about it. It should be safe to enable for
Facebook.

Test Plan:
Pasted in image and non-image links, got reasonable behavior. Verified proxying
appears to work. Verified that file:// shenanigans produce 400.

Reviewed By: tuomaspelkonen
Reviewers: aran, jungejason, tuomaspelkonen
Commenters: cpiro
CC: aran, cpiro, tuomaspelkonen
Differential Revision: 214
2011-05-03 18:49:06 -07:00
epriestley
8370f93048 Make X-Herald-Rules header sticky
Summary:
This isn't terribly elegant but it solves the problem without loss of
generality. We can pursue a more finessed solution later if it seems prudent.

Test Plan:
Created a revision matched by a blanket herald rule, and then commented on it.
Comment email had X-Herald-Rules header in it.

Reviewed By: aran
Reviewers: aran, tuomaspelkonen, jungejason
CC: aran
Differential Revision: 218
2011-05-03 06:06:57 -07:00
epriestley
7ca4835438 Simplify database initialization, fix default data
Summary:
Some users have had problems with the database initialization process, simplify
it by creating a new "initialize.sql" dump at v34.

I also populated this dump with the right landing screen (so all the tools
actually have links) and a default avatar.

Test Plan:
Dropped all databases, initialized according to documentation, ended up in a
good state with sensible defaults.

Reviewed By: jungejason
Reviewers: aran, jungejason, tuomaspelkonen
CC: aran, jungejason
Differential Revision: 210
2011-05-02 13:38:46 -07:00
epriestley
94df249775 Improve schema upgrade workflow for unprivileged users
Summary:
In a basically reasonable configuration where you connect
with a non-privileged user from the web workflow, upgrade_schema.php
won't have enough privileges. Allow the user to override the normal
auth with -u and -p.

Test Plan:
Tried to do a schema upgrade with an underprivileged user,
got a useful error message instead of garbage.

Reviewed By: Girish
Reviewers: Girish, davidrecordon, jungejason, tuomaspelkonen, aran
CC: aran, epriestley, Girish
Differential Revision: 191
2011-04-30 00:50:48 -07:00
elynde
bd0a4c0d04 Differential Updates View
Summary:
This adds a new view to differential called Updates.

The high-level goal of Updates is to enabled differential to be
effectively used without email notifications. I've tried doing things
like automatically deleting differential emails where I'm in the 'to'
line since they show up on the main diffential page but then there's
always the chance an important diff flies by without me seeing it. Also,
sometimes someone comments on a diff post-commit but differential
doesn't surface those diffs.

I re-created a test db on my devserver using mysqldump to get data on
revs > 230000 so I would have some test data. We need to add a simple
viewtime table but I didn't want to do that in production. Here's the
table:

  CREATE TABLE differential_viewtime (
    viewerPHID varchar(64) not null,
    objectPHID varchar(64) not null,
    viewTime int unsigned not null,
    PRIMARY KEY (viewerPHID, objectPHID)
  );

Issues:
  -Once we turn this on, all diffs will be 'unviewed'. What do you think
about a 'Clear All' button or something?
  -Maybe we should add a pager

This feature would be insanely useful, let me know what you think.

Test Plan:
Loaded Updates in my sandbox

  http://phabricator.dev1577.snc6.facebook.com/differential/filter/updates/

Clicked a diff, then went back, made sure diff disappeared from Updates
list

Reviewed By: tuomaspelkonen
Reviewers: epriestley, jungejason, tuomaspelkonen
Commenters: epriestley
CC: epriestley, elynde, tuomaspelkonen
Differential Revision: 169
2011-04-28 14:40:41 -07:00
epriestley
ca7a0de1cf Prevent a race in Phabricator workers
Summary: See D133. Workers can also be subject to the same race, invert the
row relationship in the same way.

Test Plan: Launched repository master daemons and some taskmasters and used
the Daemon console to veify that they were able to process tasks. Manually
checked the database to make sure data got linked correctly and that new data
was inserted correctly.

Reviewers: jungejason

CC: tuomaspelkonen

Differential Revision: 135
2011-04-14 12:09:56 -07:00
epriestley
ee1e2da8fb Avoid Timeline race condition
Summary: While I should fix the transactional stuff, that patch is going to be
tricky and transactions have some performance implications. This is a simple
fix which prevents the race.

Instead of having the data point at the event ID, have the event point at a
data ID. Insert the data first, then insert the event with the right data
pointer. This is super simple and prevents the race issue.

Test Plan:
  - Ran the schema upgrade script, verified that the database was
    correctly upgraded. Was also prompted to stop daemons.
  - Ran 'repository-launch-master', verified that the discovery daemons were
    able to discover new commits and insert events for them. Verified the
    committask daemon was consuming events and converting them into tasks.
  - Verified new tasks looked correct in the database.
  - Browsed web interface.

Reviewers: jungejason

CC: tuomaspelkonen

Differential Revision: 133
2011-04-14 10:12:10 -07:00
tuomaspelkonen
f7fe75f756 Image macros for Phabricator!
Summary:
Added long waited image macro support for differential and others.

Test Plan:
Tried a couple of different macros and made sure they appear nicely
in the comment preview. Made sure that the normal comments are shown
correctly.

Reviewed By: epriestley
Reviewers: epriestley
CC: jungejason, tuomaspelkonen, epriestley
Differential Revision: 129
2011-04-13 20:08:13 -07:00
epriestley
43449e49c0 Very basic system agent support. 2011-04-12 18:19:25 -07:00
epriestley
158a561dff Add some metamta keys. 2011-04-12 18:19:24 -07:00
epriestley
720bf02570 Missing key for large datasizes. 2011-04-10 17:25:24 -07:00
epriestley
75b11d6d7d Lint and unit star support.
Test plan: quack

Differential Revision: 35
2011-04-10 17:19:01 -07:00
epriestley
e6c5d6c8ae Properly support mailing lists, with actual testing! 2011-04-10 10:16:14 -07:00
epriestley
8218ca15b9 Turns out MySQL tables need keys. Who knew?! 2011-04-09 22:19:10 -07:00
epriestley
22297b71a0 Close the loop on Diffusion commits posting back to Differential. 2011-04-07 21:59:42 -07:00
epriestley
aa0ff43999 xhpastview 2011-04-06 22:43:56 -07:00
epriestley
5dea10e27c Fix field capitalization. 2011-04-05 22:30:10 -07:00
epriestley
11ea93260a Sync up UUIDs and create project configs. 2011-04-05 21:55:04 -07:00
epriestley
23f882a0ee Some owners write workflows. 2011-04-03 22:03:27 -07:00
epriestley
65e1386753 owners 2011-04-03 15:50:51 -07:00
epriestley
7140107ed9 Optimize session query for nontrivial number of user accounts. 2011-04-02 16:39:40 -07:00
epriestley
82fffe466a Add basic detail-parser functionality. 2011-04-01 17:11:55 -07:00
tuomaspelkonen
6b8c2d110a Merge branch 'preferences' 2011-03-31 14:30:32 -07:00
tuomaspelkonen
123fdabb75 Removed "PHID Types" storage object and interface components
Summary:
Removed because code wasn't used or really needed.

Test Plan:
* Tested that "PHID List" and "PHID Lookup" pages work correctly.
* Tested that new PHIDs can be allocated with the predefined set of types

Reviewed By: epriestley
Reviewers: epriestley
CC: epriestley
Differential Revision: 88
2011-03-31 14:01:13 -07:00
tuomaspelkonen
28fe9f4eca User preferences ported from tools
Summary:

Internal tools, e.g., differential and diffusion  have user defined
preferences for monospaced font and the option for showing either the
name of the tool or the glyph of the tool in the title.

These preferences were ported to phabricator. These preferences can be
modified in /preferences/ and they both affect diffusion and differential
at the moment.

Test Plan:

* Created an empty database
* Loaded /preferences/ and modified the monospaced font and clicked save
* Confirmed that the same page was loaded with the message that preferences
  have been saved and that the example text used the user defined font

* in /preferences/ changed the option to show tool names as plain text and
  clicked save
* Confirmed that the same page was loaded with '[Preferences]' in the title
  instead of a glyph

* These same tests were also executed for differential and diffusion

Reviewers: epriestley
CC: jungejason

Differential Revision: 91
2011-03-31 13:44:20 -07:00
epriestley
34e8d902c7 Restore "Shortcuts" feature to Diffusion. 2011-03-31 00:33:44 -07:00
epriestley
e6cf7a9cb0 More Diffusion junk. 2011-03-30 22:08:41 -07:00
epriestley
919421ead7 Derp derp, apparentl neglected to save this file. 2011-03-26 23:59:29 -07:00
epriestley
fa8f168bd0 Allow commits to be marked as 'bad' so they won't be parsed. Useful if you work
at a company where someone deleted the entire repository *cough cough*.
2011-03-26 23:52:09 -07:00
epriestley
75fcf56b67 Rough cut of Herald home controller. 2011-03-22 13:50:08 -07:00
epriestley
e1d68e852a Sorta need this file. 2011-03-20 17:55:31 -07:00
epriestley
01a20c0480 Fix various parsing bugs in Differential. 2011-03-19 14:42:17 -07:00
EC2 Default User
31d2790075 durf durf sql 2011-03-15 20:51:53 +00:00
epriestley
bb144542d3 Diffusion/phd/console improvements. 2011-03-15 13:38:14 -07:00
epriestley
4196bfb3ef Minor fixes. 2011-03-14 07:43:13 -07:00
epriestley
383b3d740c Improve some diffusioney things.
Summary:

Test Plan:

Reviewers:

CC:
2011-03-12 22:51:40 -08:00
epriestley
485b5e5ded Make the Diffusion UI vaguely usable in some cases. 2011-03-12 16:17:34 -08:00
epriestley
48b5d6d025 Diffusion change parser for SVN.
Summary: there is a small possibility this works correctly

Test Plan:

Reviewers:

CC:
2011-03-11 14:13:23 -08:00
epriestley
8bcbeface1 Increase parseriness of some parsery things.
Summary: None of these are parsnips.

Test Plan:

Reviewers:

CC:
2011-03-11 09:34:22 -08:00
epriestley
ec084ca419 Rough cut of Workers
Summary: workers do work, provided I have written them correctly. perhaps it
is so.

Test Plan:

Reviewers:

CC:
2011-03-10 13:48:29 -08:00
epriestley
57495c4287 Rough cut of repository tracking
Summary: Basic scaffolding for repository tracking, plus daemon infrastructure
(Timelines, Cursors) and some fixes (memory usage, mysql_connect() junk).

Test Plan: parsed Javelin git commit history via daemon

Reviewers:

CC:
2011-03-06 22:29:22 -08:00
epriestley
063269a00a Store OAuth tokens and more OAuth account info.
Summary:

Test Plan:

Reviewers:

CC:
2011-02-22 10:27:27 -08:00
epriestley
c3c16d0ac0 Github OAuth
Summary:

Test Plan:

Reviewers:

CC:
2011-02-21 00:23:24 -08:00
epriestley
c244d4bff2 Fully-qualify this SQL patchfile.
Summary:

Test Plan:

Reviewers:

CC:
2011-02-20 20:10:07 -08:00
epriestley
7fb9a48690 Task -> Project assocation, file uploads
Summary:

Test Plan:

Reviewers:

CC:
2011-02-20 20:08:53 -08:00
epriestley
fdd510ba17 Rough cut of projects.
Summary:

Test Plan:

Reviewers:

CC:
2011-02-20 18:41:23 -08:00
epriestley
bec2a1230c Up-to-date version of SQL.
Summary:

Test Plan:

Reviewers:

CC:
2011-02-20 13:27:57 -08:00
epriestley
2e4022aca8 Improve docs to a semi-defensible level.
Summary:

Test Plan:

Reviewers:

CC:
2011-02-11 14:58:45 -08:00