[Development] Qt 6.1.0 release note: let's use Markdown (again!)

[Shawn Rutledge]

On 2021 Apr 28, at 11:11, Jani Heikkinen <jani.heikkinen at qt.io<mailto:jani.heikkinen at qt.io>> wrote:

Giuseppe D'Angelo via Development

Hi,

On 27/04/2021 11:53, Jani Heikkinen wrote:

Initial release note for Qt 6.1.0
here:https://code.qt.io/cgit/qt/qtreleasenotes.git/tree/qt/6.1.0/relea
se-note.txt

I must say, I don't quite like the format used here.

While having the commit SHA might be useful if someone wants to look up
the commit corresponding to each changelog entry, there's a few things that
don't quite sound OK to me.

0) No 72 columns wrapping. There, I said it.

That's true. We can easily add this but is this really needed nowdays anymore (with big 4k screens)?

Newspapers have stories laid out in columns, not because the paper isn’t wide enough to write a whole paragraph across the whole page, but for the sake of readability.  But IMO it’s ok if the limit is a bit looser, like 80 or 100 or so.  When hand-editing, we never really stayed within 72 columns, because it always feels silly to put one word on the next line when you can’t find a way to shorten it to one line.

1) Quoting the commit message of a given change is hardly useful. That's why
we mandate a [ChangeLog] entry, after all; commit messages must fit in 72
columns, so they'll use a bunch of shortcuts that shouldn't be read as-is by
end users:
427da06414 QRE: discourage users from assuming that QRE stores the
subject > 5a0e5521e4 QVectorND: make some constructors explicit
86729df9d4 QTextHtmlParserNode: Limit colspan to avoid segfault

Best case scenario, they just repeat what's much better explained by the
ChangeLog message. So why adding the commit message at all?

Well, there is other opinions as well. With commit sha and commit message reader will be easy to check the change & get more information if needed. Ok, maybe commit message doesn't help that much but on the other hand it doesn't harm either...

What I was proposing last year on the mailing list is: let’s format the changelog in markdown, with proper links for the bugs: that is, the link text can just be QTBUG-xxxxx and markdown allows putting the whole URL for the link at the bottom, out of the way.

Why markdown instead of RST or one of the others?  Because it’s simple, it’s the most common, it’s not as fiddly, and it’s supported in QTextDocument.  It looks just as good when read as plain text, as the format that we already have.  Users who read it as plain text before can keep doing that.  It’s only a minor tweak to the way we did it in Qt 5.

Alternatively, for users, Markdown can be displayed as rich text in QTextBrowser, and in a plain QML Text element.  This means nicer tools for looking at changelogs are possible… on top of all the other markdown tooling that already exists in the world.  And you get to set the width at the time of viewing, so then the argument about 72 vs some other limit doesn’t matter as much.

Another idea: we could generate HTML from the markdown and make it available on the web; this is easy to automate.  We could also include it in documentation easily, if we’d rather have it there.  But without hand-editing, it doesn’t look good enough for that.

As it is, I don’t understand why changelogs are not at least installed along with Qt, by the Maintenance Tool, if we expect users to read them.

If we will get back to the tradition that module maintainers try to clean up the changelogs for their modules, then being able to use a QTextEdit-based editor is a good feature to have.  It’s dogfooding, and that will prompt us to continue fixing bugs in QTextDocument, which I think we really should continue doing.  By the way, when such an editor saves to markdown format, it gets re-wrapped, too.

We still have open governance.  The journal of record is this mailing list.  I started the discussion here… but the company did something unilaterally in spite of that, and without any discussion.  Even though I was volunteering to work on the script to improve the changelog generation!  (I was thinking of spending some free time around Christmas on that.  Good thing I didn’t?!?)  So now we have 3 scripts: the old one, the newer one that I was maintaining, and now a new one.

On the upside, relying only on the new script saves time; and maybe one changelog for all of Qt is better for users? Not sure.  On the downside, the result will never be good English without hand-editing.  The company has basically sent the message: it’s ok for changelogs to be a mess, we don’t expect module maintainers to care anymore.

Going further: documenting the link between specific changes and security fixes might end up being important, I think?  I was trying to do that when I was hand-editing.  I’m not sure if the new script does it.  But if those are listed in commit messages, they can be picked out and put into the changelogs.

(Unfortunately, my initial post did not get into the mailing list archive, for some reason.  I suspect maybe the archive software does not preserve messages that have attachments, or something like that.  But check your inbox: the title is "Proposal: let's use Markdown for the dist/changes changelog”, and it was on 2020 November 2.)

3) The messages are grouped by submodule. But submodules are not
relevant for end-users, end of story. Why there isn't a grouping per Qt
module instead? We force people to add that to ChangeLogs, only to throw
away that information?

We are hardly “forcing” ChangeLog entries.  They are much rarer than they should be, in practice.  If we want most changes to have them, the sanity bot probably needs to put a reminder on every patch that does reference a bug but does not have a ChangeLog.  (Whether that should be a -1 is debatable… but at least there should be a nag.)  But even then… native English speakers are in the minority, so it’s another chore for reviewers to make sure that those entries are phrased well enough to appear publically, and in the right mood (not imperative as in the commit summary, but present-tense as in “we now do this (instead of that)”).

3a) What about "meta" changes, like the ones we list under [Important
Behavior Changes], or [Third-Party code] or whatever? Now they're thrown
into the mix, so they don't stand out as things to watch for. I can hardly
imagine that I need to dig into the middle of [qtdeclarative] only to find a
behavioral change in the QML language.

It depends. Grouping based submodule makes it clear for the user in which repo the change is. User can't checkout the qt module but the submodule and there changes are. But I agree it could be useful to parse also tags after that [ChangeLog] tag & group entries based on that under the submodule. But to be honest those [ChangeLog] entries varies so much that it is really hard to produce clear grouping & information based on that; sometimes there is only [ChangeLog] tag, next tag after it isn't a qt module but something else etc. So producing a note which doesn't necessarily need an manual formatting isn't that straightforward (we have seen that in the past with those old changes files).

If we want good results, it still requires module maintainers to hand-edit the changelog afterwards.  But I guess most maintainers don’t want to.  I’m not sure if I still want to.  If the sanity bot starts to nag, maybe it wouldn’t need much effort anymore.

The listing of the Fixes is also questionable as well. Why not using JIRA's bug
description, rather than the commit description? At least
*that* could give better information. Is it really necessary repeating "fixes" a
thousand times?

Well, there is now SHA1, Jira ID + Jira title. Jira descriptions are inconsistent in both content and format. So I think those aren't an option. And I think 'fixes' is needed there as well but of course that can be changed to something better if most of us think it should be done. Let's just agree what the format should be and we will implement it for coming releases.

The script that I was maintaining uses those, but only if the ChangeLog is missing.  The result is definitely not usable without hand-editing, because combining the Jira title and the commit message produces redundant information, and usually both of them are badly written.  But at least hand-editing becomes possible without having to open up every bug in the browser at the same time.

So let's improve the release note to get it as good as it can be. The idea is that we can even update the already released release's note if really needed. So we don't need to postpone the releasing even if the note isn't as good as it can be. And at least coming releases will have the better one. Just let's agree what needs to be done and we try to implement improvements after that. And meanwhile anyone can manually add updates to existing one(s) for review.

Because distributed responsibility doesn’t work, and because of the chance for push conflicts, I don’t think anybody is going to be inclined to edit the one-big-changelog by hand.  If it’s split up into per-module changelogs as in Qt 5, then it’s reasonable for each module maintainer to do that.

And having changelogs in the module repos also does not preclude editing them after the fact.  Nor does it preclude another script to combine them into one changelog for all of Qt.

So what I figured we would end up with for example is qtdeclarative/dist/changes-6.0.0.md

There was still some overlap because usually I’d edit the Qt Quick bits and Ulf would edit the QML Engine bits.  But it wasn’t so much trouble with only two people.  It’s worse in qtbase though.

I suspect the long-term answer is: it’s OK for changelogs to be a mess, because we are too lazy to fix it.  Maybe most users will ignore the result, too, but then why do we bother.  It’s not like it’s easy to find anyway.

If we don’t want it to be a mess, and I end up helping to fix it, then I want my efforts to be appreciated this time.

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