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

[Richard Gustavsen]

> But I didn’t like it when we generate a point-release changelog that says
> there are only minor changes, when I know for a fact that some significant
> bugs got fixed, and should be mentioned, even though the author forgot to
> add a ChangeLog to the git commit.  So a few years ago, before each release
> I was actually scanning the git log manually to look for such bug fixes
> that ought to be mentioned.  I got tired of that because it always requires
> several windows at the same time: a terminal to view the git log, an editor
> for the changes file, and a browser with a couple of tabs open to look up
> bugs and code changes.

> Yep, same here.

Would it be better if we required all commits to have a ChangeLog entry, so that no one
forgets? And if your commit shouldn't be in the log, you need to state that explicitly, e.g: [NoChangeLog]

-Richard
________________________________
Fra: Development <development-bounces at qt-project.org> på vegne av Thiago Macieira <thiago.macieira at intel.com>
Sendt: mandag 2. november 2020 16:59
Til: development <development at qt-project.org>
Emne: Re: [Development] Proposal: let's use Markdown for the dist/changes changelog

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. The centering
can be done by removing the leading and tailing stars, then use M-x center-
line. At least, this is how it was done when I created the script.

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

> One possible bikeshed is whether we should use the easier format for
> headings like

> # QtQuick
>
> ## Animations
>
> or one that perhaps looks a bit better in the terminal, but only allows 2
> levels of headings (which is enough in practice, so far):

> QtQuick
> =======
>
> Animations
> ----------

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.

Note: the levels here are "Libraries" and "QtQuick". "Animations" is a big
bullet and "alwaysRunToEnd==true" (a bad entry) is a sub-bullet.

> But I didn’t like it when we generate a point-release changelog that says
> there are only minor changes, when I know for a fact that some significant
> bugs got fixed, and should be mentioned, even though the author forgot to
> add a ChangeLog to the git commit.  So a few years ago, before each release
> I was actually scanning the git log manually to look for such bug fixes
> that ought to be mentioned.  I got tired of that because it always requires
> several windows at the same time: a terminal to view the git log, an editor
> for the changes file, and a browser with a couple of tabs open to look up
> bugs and code changes.

Yep, same here.

> So I modified Simon’s go script to also find the
> git log entries that mention bugs, and append the git commit message plus
> extra text taken from the jira subject line.  And I just quietly used that
> script to overwrite the generated changelogs, and then edited by hand to
> format it nicely, in qtdeclarative only.  So probably qtdeclarative has had
> more-complete change logs than most other modules during the last few
> years.  I’d selectively use it to add a few qtbase changes that I wanted to
> highlight too though, now and then.  Other people were using it in other
> modules sometimes.

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.

> 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.

> We could also make the sanity bot complain when a change that includes a
> bug-fix does not include a ChangeLog entry.  But maybe that’s going too
> far?  Many non-native speakers would write badly worded changelog messages
> anyway, so just getting more developers to write “something” there does not
> remove the need for manual editing of the changes file after it’s
> generated.  But at least you’d get less-messy output from the changelog
> generator, and reliably categorized.

There's always going to be a need for an editor who understands what the
change is about.

> Maybe the commit message template should include commented-out example
> changelog lines for every possible category, because otherwise you have to
> scan the git log and look for examples each time you try to write one in a
> commit message.  At least I can’t remember all the categories that have
> been used.

The category is the class name.

> So maybe that’s one of the obstacles, why people are not
> writing them.  But the commit message template could get really long that
> way.  Or we could write some tool for editing commit messages, but… meh,
> who would use it?

I think people don't write changelogs because they don't want to repeat
themselves. Usually they've already taken the time to write the explanation in
the regular parts of the commit message and don't want to re-write. Or they
don't think the change is relevant enough to be of changelog-level notice.

> We can discuss whether we want to automatically generate changes files with
> or without all the bug fixes on a module-by-module basis.  IMO it’s too
> much for qtbase, but OK for other modules that have active maintainers who
> are willing to rewrite the markdown each time.

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

--
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel DPG Cloud Engineering



_______________________________________________
Development mailing list
Development at qt-project.org
https://lists.qt-project.org/listinfo/development
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20201103/b9ecc3f1/attachment-0001.html>