Maybe I wasn't clear enough in my first response, or I'm confused by the follow-ups. I really don't think this needs to be that complicated.

UNSTABLE-1:
- <a href="#blah-dee-blah">Blah-dee-blah got a new foo thingy</a>
...

UNSTABLE-2:
- <a href="#blah-dee-blah">Blah-dee-blah got a new bar thingy</a>
...

<h2 id="blah-dee-blah">Blah-dee-blah has changed</h2>

(issue) and (issue) Blah-dee-blah has changed since Drupal 6, in that it has a new FOO and a BAR thingy. Here's the before/after code:

...

---


The body of the document is written for people who are not chasing stable, so that we don't need to make huge changes to it before release. The ToC is organized by unstable releases so that someone chasing HEAD can get a quick summary of the changes since the last time they updated. If they already added a foo thingy, it's pretty easy to read the code and see that they need a bar thingy too.

Agreed?

-Angie

Nathaniel Catchpole wrote:

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