[Development] Documentation of new Qt features in qtdoc

[EXT Craig Scott]

On 23 Nov 2021, at 6:07 am, Edward Welbourne <edward.welbourne at qt.io<mailto:edward.welbourne at qt.io>> wrote:

On Mon, Nov 22, 2021 at 10:43:45AM +0000, Edward Welbourne wrote:
Documenting it while it's fresh in your mind generally leads to a
better description, after all,

Oswald Buddenhagen (22 November 2021 12:47) replied:
i'm not so sure about that. as seen by the quality of the [ChangeLog]
entries (in as far as present at all), many people have problems
switching their perspective to the different audience. doing that
with some temporal distance might actually help (though the "spatial"
distance of it being in a different repository certainly also helps).

The other virtue of putting the comments into a repository, rather than
commit messages, is that it opens up the option of revising them later.
So the initial description of the new feature in qtdoc may well be given
from a perspective too close to the work; but Kai's plan is to have it
in a shared repo where others (who might not have been involved in the
original review, to suggest improvements to a ChangeLog) are going to
edit the same document to add their own new feature descriptions, so
might see the deficiencies of existing entries in the file and either
improve them or poke the (by now long closed) review that added them to
ask what was meant.  So there's scope for improvement between when the
work is first described in the communal document and when that document
is finally published - just as in the wiki, but with the benefit of
past reviews on which to ask the questions and point out the problems
with particular edits to the file.

Thought I’d share how CMake’s release process handles this, for comparison.

If a change introduces a new feature or a significant behavior change, we have a dedicated directory in the repo (Help/release/dev<https://gitlab.kitware.com/cmake/cmake/-/tree/master/Help/release/dev>) where they create a file with the filename based on their branch name (basically the branch name with .rst appended). When a new release branch is created, those individual files are collected and assembled into a coherent set of release notes for that release, the whole directory for the individual files is removed from the release branch and just the files are removed from that directory on the main dev branch. The content of the individual files is expected to follow a particular format, which is easy to follow. A sample template file is always provided in that directory to make it easy for contributors.

I think Brad might have a script which helps him assemble these individual files into a single release notes page, but there is a degree of manual cleanup involved. Any work that continues on the release branch will then modify that single coherent set of release notes as part of their merge request rather than adding new files to the directory set aside for individual contributions. During the release candidate phase, we may clarify and clean up parts of the release notes page (that’s something I often do while I’m testing new features and going through the release notes with a fresh set of eyes from an end user’s perspective). When you see the full set of release notes together, sometimes you notice improvements that can be made to group related things that happened some time apart when initially contributed, or sometimes you want to improve the wording, correct typos, etc.

This process seems to work reasonably well for us. We sometimes have to ask users to add a release note for their feature during review, but that’s mostly first time contributors. Regulars seem to know what to do most of the time. From my personal perspective as a CMake co-maintainer, it has been nice to be able to edit the release notes on the release branch in a trackable form the same way I can work on other code and documentation changes (i.e. through merge requests). It’s the same workflow, so it doesn’t introduce any speed bumps to what I need to do.

Mapping this to the Qt situation, instead of individual files for each feature, Qt has the changelog entries in the commit messages. The rest of the process doesn’t sound all that different to what has been proposed here in this discussion.

Craig



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