[Development] dist/changes-x.y.z (was: Re: Branches)

[Thiago Macieira]

On segunda-feira, 10 de dezembro de 2012 23.45.44, Marc Mutz wrote:
> On Sunday December 9 2012, Marc Mutz wrote:
> > Burdening the maintainer with generating the changes file after an
> > onslaught of dozens of committers and 100s of changes without regards to
> > the changes file is - I repeat - not an attractive prospect :(
> 
> How about we make qdoc generate a listing of all \since 5.1
> functions/classes automatically?

It does that already.

> Maybe add a \change command that can be used to inject arbitrary changes
> into qdoc's changes list? Would come in handy when aspects of an existing
> function changes...

That means carrying over the change log in the documentation, which seems 
counter-productive to me. The documentation should describe what the function 
does now, with a possible not of how it changed from the past. That is, it 
should say:

  This function does foo.

  Note: prior to Qt 5.1, this function did bar.

Instead of:

  This function does bar.

  \change 5.1 this function does foo.

Moreover, there are many fixes that do not in any way alter the documentation 
of a function, but instead go to fix the function's code to match what the 
documentation required it to do.

> And the list of bugs fixed can be had from JIRA, of course.

Yes.

> That leaves a lot less commits to manually add to dist/changes, but since
> they don't stand out anymore in any reasonably machine-readable way,
> reviewers would have to ensure that for these an entry to dist/changes
> would be created.

During Qt 4.0 - 4.6 days, the changelog was a process by which each developer 
would document every change made that included a Task Tracker ID. That is, 
we'd document all bugfixes and we'd have to remember the important changes.

That's a waste of time. As you said, the list of bugs fixed can be had by 
cross-referencing JIRA and git log.

Instead, we should document in the changelog those changes that are important 
to application and library developers who use Qt. I can think of:
 - behaviour changes of any kind
 - important bugs fixed (especially those that required a workaround before)
 - new, interesting features

And on minor releases:
 - new platforms now supported and old platforms dropped
 - Tier listing

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 190 bytes
Desc: This is a digitally signed message part.
URL: <http://lists.qt-project.org/pipermail/development/attachments/20121210/c2833751/attachment.sig>