[development] Incremental upgrades

[Derek Wright]

Here's the heart of the matter...

1) DB updates are written using the core API of the version they are  
updating you to.  E.g. the 60** updates are all for the 6.x core API.

2) Drupal core's API has been known to change.

3) It's possible that an update to a particular version of core is  
using a core API function that changed or no longer exists in a  
future version of core.


So, hypothetically, the updates from 4.6.x to 4.7.x might have used  
some function in 4.7.x core that no longer exists or works the same  
way in 6.x.  If that was true, you couldn't just upgrade directly  
from 4.6.x to 6.x, since when you hit the update function that only  
worked in 4.7.x core, it would fail and then the rest of the upgrade  
path could be busted.  Therefore, first upgrading from 4.6.x to  
4.7.x, then from 4.7.x to 5.x, and finally from 5.x to 6.x, is the  
safest, since you're always running update functions against the  
version of core they were written for and tested with.

Upgrading from 4.7.0 to 4.7.1 to ... to 4.7.7 is silly and wasteful.   
To the extent the docs and release announcements give that  
impression, we should fix them.

Of course, 99% of all update functions only use a tiny fraction of  
the core API, namely the DB abstraction layer.  The DB layer doesn't  
tend to change much, so usually "skipping" some core versions when  
upgrading isn't much of a problem.

However, look at schema API new in 6.x -- for now, it's a non- 
destructive change, meaning that update_sql() or db_query() still  
work as usual.  But, it's certainly possible that, e.g. in 7.x,  
schema API changes in such a way that update_sql() no longer works as  
it once did, or no longer exists.  If that happens, it'll be  
important for sites to first upgrade all the way to the latest 6.x  
release of core, run update.php, upgrade core to 7.x, and run  
update.php again.

Also, note that update_sql() has been causing bugs and driving me and  
other developers nuts for ages, since it doesn't provide the same  
placeholder escaping/substitution functionality that db_query() does,  
even though lots of people assume it does. :(  I never got around to  
mounting a crusade around that for 6.x, but maybe I'll find time/ 
energy to do so for 7.x (if schema API doesn't totally change  
update_sql() by then, anyway).  So, it's in fact quite likely that  
*something* about the API we use for update.php will change in 7.x,  
and that means upgrading directly from 4.7.x or 5.x to 7.x might not  
work.

If that happens, we should definitely document it clearly in numerous  
spots, but otherwise, I think the boiler-plate text we've been  
cutting and pasting in release announcements is probably misleading  
and should be either removed or clarified based on this info.

Cheers,
-Derek (dww)