[Development] Proposal: let's use Markdown for the dist/changes changelog

[Shawn Rutledge]

On 2 Nov 2020, at 16:59, Thiago Macieira <thiago.macieira at intel.com<mailto:thiago.macieira at intel.com>> wrote:

On Monday, 2 November 2020 02:26:31 PST Shawn Rutledge wrote:
So in practice, changelogs still require manual editing.  Probably there is
someone who knows just what settings to use in just what editor to make it
effortless, but for me it always involves a lot of tedious manual spacing,
because paragraph indentation is so damn weird (5 spaces usually), etc.
Creator doesn’t know how to wrap a paragraph in a changelog, for example.
There is no tool to center the text inside the star-box headings except for
the generator scripts themselves, AFAIK.

Emacs works just fine. You just need to add spaces before and after the -
lines so it detects what's a paragraph, then use M-q to rewrap.

I tried.  (I’m not an emacs user normally, but I’ve tried before; this time had to read some docs again to refresh my memory.)  The wrapping still didn’t seem right to me.

But I wholeheartedly agree on changingi to either Markdown or ReStructuredText
for the headings and the bullets.

I’m glad you agree.

RST allows for far more levels even in the more verbose way. Anyway, since we
only use two levels anyway and I think we should avoid adding more levels, I
would prefer the more verbose way.

OK.

Extracting extra entries is a welcome addition. If you can just mark the
entries thus extracted so we know what was written as an intentional changelog
and what is speculative and thus requires more attention.

I think it’s clear already if one reads all the way through: the generated entries end with the text “The bug was:” with the Jira subject line, and often a lot of verbosity from the git commit message.

Then it was proposed that we might as well use the go script all the time.
And the result is what you can see now:
https://codereview.qt-project.org/c/qt/qtbase/+/319071  Nobody wants to
edit such a long changelog, instead they are just complaining that it’s a
mess.  I was able to deal with this in qtdeclarative; I don’t mind the
mess, because it means I get all the information I need in the editor I’m
using, and I take it for granted that the changes file needs manual editing
anyway.  But in qtbase it’s a lot of changes, and it will be a lot, each
time.  Some people say if the author didn’t write a ChangeLog, tough luck:
the change will not be mentioned.

6.0 is a very special case. For other releases, especially point releases, I
can see the value.

Yes but that link is for the 5.15.2 changelog.  Which I’ve now done a few hours’ manual editing on.  It’s amazing how many interesting bug fixes would be omitted if we only used the ChangeLog entries.

The category is the class name.

The script can get the categorization from the ChangeLog entry if there is one; but in the case that there isn’t, I doubt I will try to make it smart enough to figure out what was the main class that got changed, since patches often touch multiple classes.  So for humans to edit afterwards, broader categories make it easier and more succinct.  But yes, I see many changes files are using class names as categories.

A full listing of what has been fixed, appended to the file, is not a bad idea
anyway.

I could try to make the bugs into reference links: inline they'd look the same as they already do:

- [QTBUG-12345] Fixed a bad bug in QVariant.

and then at the bottom of the whole file, a long list of URL definitions for every bug mentioned:

[QTBUG-12345]: https://bugreports.qt.io/browse/QTBUG-12345 "QVariant conversion to QChar fails"

Then HTML rendering will make real clickable links out of the inline references and omit the list at the bottom (it also works directly in QTextBrowser when you read that markdown: links are clickable); whereas otherwise  [QTBUG-12345] is rendered as plain text in brackets if the link url is not defined elsewhere.  Reference links are something else that QTextMarkdownWriter doesn’t rewrite yet, but it can be done.  (And no problem to make the go script ganerate them, anyway.)

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20201102/9fbf1c84/attachment-0001.html>