[racket-dev] Release Announcement for v5.1.2

On Mon, Aug 1, 2011 at 3:11 PM, Matthew Flatt <mflatt at cs.utah.edu> wrote:
> At Mon, 1 Aug 2011 15:03:21 -0400, Sam Tobin-Hochstadt wrote:
>> There's certainly limited space for the most prominent elements of the
>> release notes.  But I think the right solution there is to pick some
>> small number of items (say, 5) that are most significant, and
>> highlight them.  Then much more can be included below that, and
>> finally some information about minor changes (fixed bugs, for
>> example).  The git release notes are an example of this style:
>> http://kernel.org/pub/software/scm/git/docs/RelNotes-1.7.0.txt
>
> My preference is that *release notes* in the docs/distribution have no
> limit, but a *release announcement* includes highlights only.

That seems reasonable, but traditionally our release announcements
have not mentioned the existence of release notes.  Probably for the
reason below ...

> Few parts of our distribution currently have release notes:
>
>  http://docs.racket-lang.org/release/index.html
>
> In some past cases, such as web server changes, I wished that we had
> more release notes. Maybe we need more sections on that page, or maybe
> the notes should be reorganized into one big set of notes.

Right now, I think the release notes are mostly organized (implicitly)
by who is responsible for them.  A simple revision might be just to
organize based on the distribution specs (so racket-textual, racket,
racket-full).  That would both simplify the current set of sections,
and make it clearer where new things should go.
-- 
sam th
samth at ccs.neu.edu