gnuchangelog

A simple parser of GNU-format ChangeLog files

The GNU change log format is a long-standing convention for GNU packages and those using the autotools build system. But it has several downsides in modern use, particularly:

• Frequent version-control conflicts from differing interweaving of change entries;
• (Because) each change is recorded by its author and date of authorship, rather than grouped as release documentation, which is the real intent.
• Lack of standard structure for indicating releases or categories of change.
• The format cannot be easily formatted for e.g. HTML presentation (unsurprisingly, as it pre-dates Markdown and RST, and possibly even HTML.)

This package just parses the GNU ChangeLog format, to aid with either conversion to a more modern format without these defects (such as the Markdown-based KeepAChangelog (KAC) format) or for custom presentation or analysis.

Usage

The use is trivial: the gnuchangelog.load() function accepts a file object or filename argument (and see also loads(), from a string) and returns a list of CLEntry objects in the order found in the ChangeLog (i.e. usually newest to oldest).

These objects have three properties: .text, .author, and .date. The author property is a CLAuthor object with properties .name and .email; the date property is just a string, though conventionally should be in yyyy-mm-dd order and easily convertable to a Python datetime if needed.

A conversion script from GNU to KAC format is maintained in the project repository, but not installed as the heuristics for guessing change-entry categories

TODO's

• split the .text parsing around the first colon, into the leading "affected files" part, and the descriptive text? For now, leave to the user as this is often not used.