[development] Documentation needed: new format for update_N hooks

[Barry Jaspan]

Angie,

I started writing Schema API docs; the work in progress is at
http://drupal.org/node/146843.  (Before the 4-week extension, ) I
decided to delay finishing the docs until after code freeze so I could
work on other patches, but I'll get back to it eventually.  If you
want to help, by all means do so. :-)

system_update_6022() looks pretty good to me.  The API functions
should be pretty self-explanatory.

The tricky part will be explaining why you can't use your own
hook_schema in an update function.  See
http://drupal.org/node/144765#comment-245805.

Also, system_update_6020() (note: not 6022) reveals that the
db_create_table() API function needs to change.  It needs a
$table_name argument, or else you have to do all that ugly stuff with
drupal_get_schema_unprocessed() and _drupal_initialize_schema().  I'll
submit an issue for this Real Soon Now.

Also also, I think hook_schema() should be moved into .install files;
we do not need .schema files.  Dries independently commented on my
blog that he thinks so, too.  So, I'll be submitting a patch for that,
too.

Thanks,

Barry