[development] Documentation needed: new format for update_N hooks

[Angela Byron]

On 4-Jun-07, at 9:01 AM, Barry Jaspan wrote:

> 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.

Sure, I understand. It's just that the lack of these documents is now  
actively hampering core development, as people are either totally  
confused on what update paths need to look like now, or aren't aware  
that anything changes and are doing them the old crappy way still.  
The schema API isn't mentioned at all in the update docs currently,  
and not everyone is subscribed to the commit messages.

So I made the following changes to the module update page: http:// 
drupal.org/node/114774#schema-api

a) I added a note about the schema API addition, pointing off to the  
schema API docs.
b) I added a before/after comparison of hook_install()
c) I added a before/after comparison of hook_uninstall()
d) I added a before/after comparison of hook_update_N()

Please review and make sure I'm not talking out of my behind. ;)

Also, please note that it really is _critical_ to have API changes  
mentioned here ASAP after a patch is committed. It's fine if more  
extensive documentation comes later, but this page is the definitive  
resource for core and contrib developers during a code thaw and needs  
to track what is happening as closely as possible.

-Angie