On Tue, 23 Nov 2021 at 09:39, EXT Craig Scott <[email protected]> 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
_______________________________________________ Development mailing list [email protected] https://lists.qt-project.org/listinfo/development
