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

[Larry Garfield]

Only in Drupal would "blah-dee-blah" be "putting it so clearly". :-)

That said, what webchick says below (when she's supposed to be on vacation) 
makes sense.  My point earlier wasn't that we shouldn't split the TOC by 
unstable tag, but that once unstable-2 is out, we really shouldn't expect 
anyone to *then* port anything to unstable-1.  We want them to be going to 
unstable-2.  

Also, for the record, ? for DB placeholders was considered bad form (at least 
by me) even before DBTNG was committed as it is less self-documenting.  
Although the code does not currently forbid it, ? was not included in any of 
the documentation for DBTNG since, um, the original Barcelona presentation a 
year ago. :-)  Certainly never in anything official.

On Tuesday 14 October 2008 6:37:23 am Nathaniel Catchpole wrote:
> Yeah, that's what I meant, thanks for putting it so clearly :)
>
> Nat
>
> On Tue, Oct 14, 2008 at 12:07 PM, Angela Byron wrote:
> > 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)



-- 
Larry Garfield
larry at garfieldtech.com