[Development] Qt 6.1.0 release note

[Paul Wicking]

On 4/28/21 11:11 AM, Jani Heikkinen wrote:
> Hi!
> 
> And thanks for your feedback! Some comments below.
> 
> 
>> -----Original Message-----
>> From: Development <development-bounces at qt-project.org> On Behalf Of
>> Giuseppe D'Angelo via Development
>> Sent: tiistai 27. huhtikuuta 2021 17.54
>> To: development at qt-project.org
>> Subject: Re: [Development] Qt 6.1.0 release note
>>
>> 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)?

Yes, it is needed. It's an ergonomics issue that has seen a rather 
substantial amount of research. The exact width is still a matter of 
dispute, but the general concern is about reducing the need for eye (or 
worse, head) movement on behalf of the reader.
> 
>>
>> 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...

This feedback is not unique, see e.g. the comment section at 
https://www.qt.io/blog/commercial-lts-qt-5.15.3-released.
> 
>>
>> 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?
>>
>> 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).

The end user might not care at all about which repository it is in (why 
then would they care about the installer?), but they certainly do care 
about which modules are involved. Furthermore, I don't think ChangeLog 
entries being of poor quality is a strong argument for coming up with 
something that is possibly worse. Rather, it exposes an issue that we 
can address through this very mailing list.

//! Paul
> 
>>
>> 4) Also why not grouping by class? If now I want to find all the changes to
>> QString, I have to read the entire [qtbase] thing. Again this is information
>> present in the [ChangeLog]s that is getting binned.
> 
> A comment above pretty much answers to this already. And in addition: Most probably there isn't [ChangeLog] tags in every QString related changes so you can't get all those anywhere but from git log
> 
>>
>>
>> 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.
>>
>>
>>> Please review it and do needed modifications as a new change(s) in the
>>> release note
>>> repository:https://codereview.qt-project.org/admin/repos/qt/qtreleasen
>>> otes
>>
>> I don't see the changes to QList/QVector/QString/QByteArray behavior that
>> have just landed, for one.
> 
> Yes, those are missing from the note; initial one was done based on RC. Plan was to update the note when final content is in place. And just to clarify: Those changes didn't contain any [ChangeLog] tag so only bug fix section fill contain entry/entries for those. If those needs to be in 'Important Changes' section someone needs to add that manually; script won't notice those.
> 
>>
>>
>>> Target is to release Qt 6.1.0 Thu 6th May and so on it would be good to
>> have needed updates in before that.
>>
>> So not even a RC2 after, indeed, changing the behavior of the top X most
>> used classes in Qt? (Certainly of the most used one.) Oh well, I won't
>> repeat my (unanswered) questions and remarks from QTBUG-91360.
> 
> RC2 will be published later this week with the fixes for this one.
> 
> 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.
> 
> I attached a sample of parsed [ChangeLog] entries from qtbase to indicate the inconsistency of entries. How the script should parse lines e.g. 7, 11, 21, and 28 ?
> 
> br,
> Jani Heikkinen
> Release Manager
> 
> 
> _______________________________________________
> Development mailing list
> Development at qt-project.org
> https://lists.qt-project.org/listinfo/development
>