[development] Announcing DRUPAL-7-0-UNSTABLE-2

[Angela Byron]

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 <drupal at dwwright.net 
> <mailto:drupal at 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)
> 
> 
> 
>