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
signature.asc
Description: This is a digitally signed message part.
_______________________________________________ Development mailing list [email protected] http://lists.qt-project.org/mailman/listinfo/development
