QUIP 17 | Change log creation

QUIP:17
Title:Change log creation
Version:cfcb7178907d3229a04ea79b528335b7dec8bdc6
Last-Modified:2020-09-03
Author:Mitch Curtis
Status:Active
Type:Process
Created:2020-08-25
Post-History:https://lists.qt-project.org/pipermail/development/2019-November/037927.html

Overview

The Qt framework uses change logs as a means of informing users about new features, important behavior changes, and bug fixes. Before each release, a change log file is generated from the section of git commit messages that start with the [ChangeLog] keyword.

Content

Do include: - Noteworthy features - Significant changes - Changes that affect many users - Changes that affect compatibility - Changes to information about third-party code (see QUIP-4)

Do not include:

  • Fixes in tests
  • Documentation fixes
  • Pure code cleanup or refactoring
  • Fixes for regressions introduced in not-yet-released commits
  • Anything that is not relevant to users

Format

  • A [ChangeLog] entry may span multiple lines and ends with an empty line.

  • You may add more than one [ChangeLog] entry, each in a separate paragraph, if there are several ways the change affects users.

  • Each entry starts with a sequence of tags, each in square brackets, the first of which is [ChangeLog].

    • If the Git repository contains multiple modules, use the module name as a tag to indicate the area of the change, e.g. [QtCore].
    • Optionally specify a class or subtopic as an additional tag, e.g.: [QtNetwork][QSslSocket]
    • Other common tags are:
      • [General]
      • [Important Behavior Changes]
      • [Deprecation Notices]
      • [Platform Specific Changes]
      • [Windows]
      • [macOS]
      • [Linux/XCB]
      • [Third-Party Code]
  • After the tags, describe how the change impacts users of the relevant component.

    • Try to integrate the ChangeLog entry into the surrounding commit message to avoid redundancy.
    • If the change resolves a security issue, summarise the issue and mention any relevant CVE or kindred identifiers.
    • The description should use either simple past ("Fixed …") or be explicit about referring to the current state ("… does now …").
    • Make sure the entry is reasonably self-contained. If you fail to formulate a meaningful description, it's probably not useful information to start with.
  • In summary, the entry should look like this:

    [ChangeLog][module][class/topic] description of the really important change
    that was just made (on several lines).
    

Tools

The createchangelog tool in the qtqa.git module is currently the most feature-complete tool for change log creation. Documentation for it can be found in its README under src/createchangelog.