Metadata-Version: 2.4
Name: gnuchangelog
Version: 0.0.2
Summary: A simple parser of GNU-format ChangeLog files
Author-email: Andy Buckley <andy@insectnation.org>
License-Expression: Apache-2.0
Project-URL: Repository, https://gitlab.com/agbuckley/gnuchangelog.git
Project-URL: Issues, https://gitlab.com/agbuckley/gnuchangelog/-/work_items
Keywords: changelog,change log,gnu,autotools,keepachangelog,development
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# gnuchangelog

## A simple parser of GNU-format ChangeLog files

The [GNU change log
format](https://www.gnu.org/prep/standards/html_node/Change-Logs.html)
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](https://keepachangelog.com/) (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.
