[Development] Documentation of new Qt features in qtdoc

[Jason McDonald]

On Tue, 23 Nov 2021 at 09:39, EXT Craig Scott <craig.scott at qt.io> wrote:

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

Thank you for sharing, Craig. I like this approach.  It seems relatively
simple and leaves a good audit trail.

Over the past 15+ years, the changelog/release-notes topic has been debated
on this list many times, with many proposals for process changes and
various kinds of automation (some of which were prototyped but rapidly fell
into disuse). Despite all of that effort, I'm not convinced that we've
really made the task much easier for the release team than it was when I
became Qt's release manager in 2008.

As someone who has spent a goodly part of the past twenty years trying to
give my customers high-quality release notes and changelogs that are a
genuinely useful and informative basis for decision-making, including a few
years doing so for Qt, I have come to see trying to fully automate that
task as a bit of a fool's errand.  The more I have thought about this
problem over the years, the more I think it's best to acknowledge that
there is no perfect solution and just keep it fairly simple for developers
while trying to minimise the pain for release folks.

Once upon a time, I idealistically thought we could automate the process if
developers would just learn to do The Right Thing(TM), but with greater
experience I now recognise that it isn't reasonable to expect a large team
of developers to produce documentation that reads consistently for style
and tone as if it was all written by one author, to have all the fragments
magically fit together in a logical order, or to understand how high-level
corporate or marketing goals for a particular release might influence how
certain items get described and which items get emphasised above the others.

Rather, I now expect that there must inevitably be significant human input
in assembling release notes if they are going to be substantially more
useful to customers than a 'git log' (and if they're not substantially more
useful, why would be bother in the first place?).

For each release, I expect to spend some time to massage fragments of text
into a consistent format, tone and tense, to reword internally-focused
change descriptions into more customer-focused ones, to merge multiple
related change descriptions (e.g. if the same code changed multiple times
between releases, I want to describe how it ended up, not the intermediate
states that customers will never see), to categorise changes into different
types (e.g. feature, bug-fix, etc.), and to pick out the most important
items that should be highlighted for users who aren't going to read the
whole list (which is probably most users).  Those highlights may also be
reused in release announcements and marketing materials.

I see this as a task for someone who has both technical writing skills and
development skills (or at least a good overview of Qt's structure and
feature set), so that they can understand, at least at a high-level, the
changes they are trying to describe for users.

The person or team doing this work needs a few key pieces of information
about each change to give them a good starting point and make the task
relatively painless.  Ideally, they shouldn't have to resort to reading git
logs or reading whole patches (though in my days as release manager, I did
rather a lot of that when writing release notes).  A template, such as the
one mentioned by Craig, is a good prompt for the required info.

For Qt release notes, I usually wanted to know:
* the affected component (much easier now that Qt is modular),
* the type of change -- new feature, bug-fix, docs, cosmetic/cleanup (the
latter might be merged into one line or omitted from release notes
entirely),
* related changes (in case it makes sense to merge into one description),
* whether the change supersedes an earlier one (so I can drop the earlier
one's description),
* whether the change reverts part or all of an earlier change in the same
release (so I can drop or amend the earlier change description),
* whether the change reverts something from an earlier release (that
probably needs to be highlighted in the release notes),
* any special status information (e.g. deliberate source- or
binary-compatibility breakage, tech-preview for which source- or
binary-compatibility promises are not being made, etc),
* related Jira tasks,
* who can answer questions if I need more information.

With the right template, the process Craig outlined would provide all of
that information.

Cheers,
--
Dr. Jason McDonald
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20211123/0f900295/attachment.html>