6.3.4. Common errors in changelog entries

The following examples demonstrate some common errors or examples of bad style in changelog entries.

  1. * Fixed all outstanding bugs.

This doesn’t tell readers anything too useful, obviously.

  1. * Applied patch from Jane Random.

What was the patch about?

  1. * Late night install target overhaul.

Overhaul which accomplished what? Is the mention of late night supposed to remind us that we shouldn’t trust that code?

  1. * Fix vsync fw glitch w/ ancient CRTs.

Too many acronyms (what does “fw” mean, “firmware”?), and it’s not overly clear what the glitch was actually about, or how it was fixed.

  1. * This is not a bug, closes: #nnnnnn.

First of all, there’s absolutely no need to upload the package to convey this information; instead, use the bug tracking system. Secondly, there’s no explanation as to why the report is not a bug.

  1. * Has been fixed for ages, but I forgot to close; closes: #54321.

If for some reason you didn’t mention the bug number in a previous changelog entry, there’s no problem, just close the bug normally in the BTS. There’s no need to touch the changelog file, presuming the description of the fix is already in (this applies to the fixes by the upstream authors/maintainers as well; you don’t have to track bugs that they fixed ages ago in your changelog).

  1. * Closes: #12345, #12346, #15432

Where’s the description? If you can’t think of a descriptive message, start by inserting the title of each different bug.