Upgrading world from 5.0-dp1 to 5.1-RELEASE

[Chuck Swiger]

Andre Guibert de Bruet wrote:
[ ... ]
> I'm of the opinion that UPDATING should be shortened for CURRENT. We
> stopped supporting 5.0-RELEASE, why are we including every change since
> 4.x? What there should be is an UPGRADING file for users that are running
> anything other than what's current (5.2-CURRENT as it currently stands)
> and an UPDATING file for users that don't need the two tons of steps and
> FYIs. For HEAD, for example, UPDATING would only include the changes since
> the last release (Currently 5.2-RELEASE, soon 5.2.1).

The UPDATING file contains a prologue and reference to "COMMON ITEMS", 
followed by a cronological ChangeLog, then followed by the COMMON ITEMS 
section.  Your mileage may vary, but I suspect that starting with COMMON 
ITEMS, and then making reference to a seperate ChangeLog file would be easier 
to maintain and would be more readable.

A user who wanted to update their system would receive prompt gratification by 
seeing a section on how to build the kernel and how to build and install world 
  on the first page of UPDATING, rather than ~1300 lines into that file.

How much of the ChangeLog to include is a seperate question, but it would be 
reasonable to rotate it when needed, or perhaps even have a ChangeLog-4 and 
ChangeLog-5 if it's easier on people to track changes made to -CURRENT versus 
-STABLE seperately.

-- 
-Chuck