The idea wasn't to merge everything, but it's to only keep the most recent version of any particular API.

For example, hook_nodeapi just got split up, there's a chance the $a3 and $a4 arguments might get removed too. I don't see that having a single 'hook_nodeapi has changed' entry makes things any more confusing than having two separate entries with somewhat conflicting information if it's a bit different between two unstable versions.

Similarly when dbtng was first committed, people were encouraged to use ? placeholders and :named placeholders interchangeably - we now only recommend :named placeholders due to query logging - surely it's better to have a single line on this than have the docs change all the way through. Same for permissions arrays getting the extra 'title' index etc.

I can't think of many other things where a particular upgrade instruction would have to change between one unstable release and another - so IMO it's better to have one block of documentation in those (fairly rare) cases than two contradictory and partial ones. Everything else would still be grouped by unstable release. So far, the differences have all be pretty minor, we could always leave a note in the earlier documentation saying 'this change was subsequently revised, see below and '#issue'.

Nat

On Tue, Oct 14, 2008 at 9:07 AM, Derek Wright <drupal@dwwright.net> wrote:

On Oct 14, 2008, at 1:00 AM, Derek Wright wrote:

If this high-signal info is not in CHANGELOG.txt, there's not a release node, and it's not in the upgrade docs, where do y'all propose to put it?

p.s. If life swallows me whole, spits me out 3 weeks later, and I missed an unstable, it'd sure suck if the upgrade docs have all been "merged" again except for unstable2 => unstable3. I don't see any value in destroying this information once we have it. If we think the upgrade docs will get too confusing if the table of contents (TOC) is organized by unstable, then we need a different solution. But we need something that preserves the high-signal info about API changes for each unstable, since we can't be sure who needs which parts of it.

I don't see anything wrong with keeping the TOC organized by unstable during the entire lifecycle of unstable. Once we hit beta1, we can move the per-unstable TOC stuff to the bottom of the page as an appendix, and make a new merged TOC organized by importance or subsystem or however else people think the info should be merged for the "final" doc.

Cheers,
-Derek (dww)