[Development] How to write a ChangeLog entry

Thiago Macieira thiago.macieira at intel.com
Mon Jan 20 21:08:37 CET 2014


Hello everyone

I've attached the raw output of the Qt 5.2.1 changelog, as created by the 
create_changelog.pl tool. As you can see, it has several mistakes. This email 
is meant to explain how to properly write a changelog entry in your commit 
message.

The basic format is:

[ChangeLog][Major area][Minor area] Text with a verb in the past, like 
"added", "fixed", "made" if you're describing the issue that was fixed. 
Alternatively, you can say what Qt will now do, as in "ClassName will now do 
that" if the new behaviour is more important. Constructs like "now does" and 
"no longer does" are acceptable to indicate future behaviour (present 
continues to the future or "general truth" sentences).

Notes:
 * you can add as many [ChangeLog] blocks as necessary to your commit message

 * only add them if you have something important to tell the user. You do not 
have to write an entry for every commit and fix you do.

 * each block MUST be a single Git commit message paragraph. That is, there 
must be a blank line before and one after. That means: the Change-Id or Task-
Number lines must be separated from the ChangeLog paragraph

 * if you need continuation lines, you need to insert a non-empty blank line. 
It's very hard to do it in a regular git commit, since you need to pass the --
cleanup=verbatim option, but you can insert NBSP instead.

 * it's ok to word-wrap the paragraph. The script will re-wrap as necessary 
and strip any leading or trailing whitespaces.

 * the task number is automatically extracted. Do not add it.

 * the "Major area" should be the Qt module name, a platform name or a tool 
name

 * the "Minor area" is optional, but you can use it to describe a subsystem of 
the major area, like a class name. If you can't think of anything, don't use 
it. If the "Major area" isn't a Qt module, consider not using a minor one.

 * it's possible to use a "Micro area" (and "nano area" and so forth), but you 
should think about it first.


Mistakes in the attached file:

 - QTBUG-34989:
   * [QTBUG-34989] Pick up plugins from deployment location of Active X
     DLLs.

 - QTBUG-35129:
   * [QTBUG-35129] Update deployed plugins and imports when APK is updated
     on the device.

Do not include the task number in the changelog line. It's extracted 
automatically.

Messages should be with verbs in the past or future, not present or 
imperative.

 - Make mailto links work again in Qt Assistant:

 - Editable Combobox would not update
currentText when accepting a substring of an existing value.:
   * [QTBUG-35521] 

 - Fixed: TableView regression where
the last row in a TableView could not be selected by keyboard.:
   * [QTBUG-35572] 

The changelog message was in brackets, making it an area:
[ChangeLog][Qt Assistant][Make mailto links work again in Qt Assistant]

The colon after "Fixed" should not be there. Make it a sentence.

 - General:
   * Applications no longer need to register common Qt Positioning data
     types with the metatype system.

Small issue. The "General" minor area is optional, you can leave it out.

   * [QTBUG-33345] Support custom port number Reviewed-by: Mark Brand
     <mabrand at mabrand.nl>
   * [QTBUG-13435] Fixed the internal state of IBase driver after a failed
     open call Reviewed-by: Mark Brand <mabrand at mabrand.nl>
[and others]

Missing blank line after the [ChangeLog] paragraph.

qtbase
------

"qtbase" is not an area, it's an organisation detail of the packages. The 
correct area would be "Tools".

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center
-------------- next part --------------
Accessibility
-------------

 - On Linux action names were returned as empty strings in AT-SPI
   getActions, now returns the proper names.

ActiveQt
--------

 - QTBUG-34989:
   * [QTBUG-34989] Pick up plugins from deployment location of Active X
     DLLs.

Android
-------

 - [QTBUG-34984] Add workarounds for OpenGL bugs on Samsung Galaxy Tab 3.

 - QTBUG-35129:
   * [QTBUG-35129] Update deployed plugins and imports when APK is updated
     on the device.

Important Behavior Changes
--------------------------

 - [QTBUG-34345][QTBUG-26008][QTBUG-26430] QPrinter no longer allows you to
   set an invalid printer name.
 - [QTBUG-34141] Parsing of Qt::ISODate by QDate::fromString() and
   QDateTime()::fromString() is not as lenient as before, the date
   component separators are now required to be non-numeric. This means a
   string like "2000901901" will no longer be recognized as a valid ISO
   Date, but "2000/01/01" will still be even though it doesn't strictly
   meet the ISO format of "2000-01-01".

Platform Specific Changes
-------------------------

 - OS X:
   * [QTBUG-34411] Implemented QMainWindow::setUnifiedTitleAndToolBarOnMac.

 - OS X / QtPrintSupport:
   * [QTBUG-34700] Respect the custom paper size settings when printing.

 - X11 / XCB:
   * [QTBUG-32683] Fixed a bug that caused Qt applications to think the
     screen DPI had changed when it had not, after connecting or
     disconnecting monitors.

Qt Assistant
------------

 - Make mailto links work again in Qt Assistant:


Qt Quick Controls
-----------------

 - Editable Combobox would not update
currentText when accepting a substring of an existing value.:
   * [QTBUG-35521] 

 - Fixed: TableView regression where
the last row in a TableView could not be selected by keyboard.:
   * [QTBUG-35572] 

QtBluetooth
-----------

 - Documentation:
   * Fix cases where device and service discovery classes emitted an error
     signal but the human readable error string was not adjusted.

QtCore
------

 - [QTBUG-35069] Fixed a bug that caused negative number input using '-' to
   be rejected because the current locale uses e.g. 0x2212. QIntValidator
   and QDoubleValidator now accepts both signs as well as the locale minus
   sign.
 - Fixed sign conversion warnings in code using QMetaTypeId.

 - QTemporaryDir:
   * Fixed bug in QTemporaryDir name generator that dramatically reduced
     randomness of the name.

 - QThread / Windows / QTBUG-34840:
   * [QTBUG-34840] Fix handle leak.

 - Windows:
   * [QTBUG-35357] Fix regression from Qt4 in QProcess. It wasn't possible
     anymore to alter pipe modes of stdin in child processes.

QtGui
-----

 - [QTBUG-35421] Fixed crash when sending accessibility updates when the
   corresponding widget does not have a corresponding QAccessibleInterface.
   This showed on Mac for example with QStatusBar.
 - Qt's generic font database now adds OpenType fonts (.otf).

 - OS X / QKeySequence:
   * [QTBUG-24406] return Qt::Key_unknown with invalid modifiers on OS X

QtMultimedia
------------

 - Android:
   * [QTBUG-31422] Enable mediaplayer to read files from the Qt Resource
     system.
   * [QTBUG-35564] camera operations moved to a dedicated thread
   * [QTBUG-35416] QVideoProbe support for camera

QtPositioning
-------------

 - General:
   * Applications no longer need to register common Qt Positioning data
     types with the metatype system.

QtQml
-----

 - [QTBUG-35979] Fix JavaScript Array.pop() not updating the internal array
   length correctly

QtQuick
-------

 - [QTBUG-35128] Fixed TextInput to call fixup() on its validator when
   being accepted or losing focus, and the validator reports that the input
   is in "intermediate" state ie. the input should be fixed up.
 - [QTBUG-34517] QQuickTextInput would not accept
   delete/home/backspace/left/right keys when the key was used in a
   shortcut.

QtQuickControls
---------------

 - Mac: ComboBox will only get tab focus when it is editable.
 - [QTBUG-35794] ComboBox: Allow setting currentIndex to -1 to clear
   selection

QtSql
-----

 - QIBASE:
   * [QTBUG-33345] Support custom port number Reviewed-by: Mark Brand
     <mabrand at mabrand.nl>
   * [QTBUG-13435] Fixed the internal state of IBase driver after a failed
     open call Reviewed-by: Mark Brand <mabrand at mabrand.nl>

 - QMYSQL:
   * [QTBUG-31124] Fix sub-second handling Change-Id:
     I5718868029bdedab9508213e800d2dcf3da9be9a Reviewed-by: Giuseppe
     D'Angelo <giuseppe.dangelo at kdab.com> Reviewed-by: Mark Brand
     <mabrand at mabrand.nl>

 - QOCI:
   * [QTBUG-34794] Fix compilation Reviewed-by: Mark Brand
     <mabrand at mabrand.nl>

 - QSQLITE:
   * [QTBUG-24200] Fix sub-second handling Change-Id:
     Ib89152b7c3dd780b57a8826beff8b6b118e9d3d6 Reviewed-by: Giuseppe
     D'Angelo <giuseppe.dangelo at kdab.com> Reviewed-by: Mark Brand
     <mabrand at mabrand.nl>
   * [QTBUG-35186] Fixed evaluation of driver options Change-Id:
     I8e74fe1ce43b9118b15f7b13fc71670bdcd73f68 Reviewed-by: Giuseppe
     D'Angelo <giuseppe.dangelo at kdab.com> Reviewed-by: Mark Brand
     <mabrand at mabrand.nl>

QtTestLib
---------

 - [QTBUG-34630] The (default) plain text logger on Windows now logs to
   either the system debug log (in case no console is open), or stdout, not
   both.

QtWidgets
---------

 - QSpinBox:
   * [QTBUG-20691] Entering positive values with the '+' prefix is now
     allowed.

 - Windows:
   * [QTBUG-34799] Update QWidgetBackingStore and QWindowsBackingStore to
     support Qt::WA_StaticContents QWidgetBackingStore::staticContents()
     was updated for windows to *not* unconditionally return false. It now
     returns true if it has a non-empty static widgets list.
     QWindowsBackingStore::resize(...) was updated to honor the provided
     static contents region. It now copies the static region into the new
     backbuffer in a manner similar to what was done in Qt4. The difference
     is that this version accounts for the possibility of the new buffer
     having a smaller region than the old buffer. In Qt4 the
     ::prepareBuffer method was only called when the buffer was resized
     larger.

Text
----

 - QTBUG-35740:
   * [QTBUG-35740] Fixed regression when shaping some strings containing
     characters from multiple fonts.

Windows
-------

 - [QTBUG-8361] Don't cover the taskbar when maximizing frameless windows.

androiddeployqt
---------------

 - QTBUG-35401:
   * [QTBUG-35401] Speed up debug deployment.

qtbase
------

 - qmake:
   * [QTBUG-35530] fix detection for multiple VS installations
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 190 bytes
Desc: This is a digitally signed message part.
URL: <http://lists.qt-project.org/pipermail/development/attachments/20140120/21ba29ec/attachment.sig>


More information about the Development mailing list