Using a ChangeLog as a canonical source of package metadata (was: Announce: PyPrimes 0.2.1a)

[Steven D'Aprano]

Ben Finney wrote:
[...]
> The perils of duplicate sources of information: a Changelog makes claims
> about which version is latest, but the packaging metadata comes from
> somewhere else.
> 
> This problem is addressed quite well, in my opinion, by the Debian
> packaging tools. The tools by default read the following information:
> 
> * release version string
> * maintainer name
> * maintainer email address
> * target suite (a conceptual “which Debian version should this go into”)
> 
> from the Changelog document, automatically. This means that the
> Changelog document, as well as being directly useful to the recipient as
> a text document, becomes the canonical place to record all those fields
> for the packaging tools to read. No need to maintain duplicate records.

A very interesting way to handle this, and one which deserves further
configuration.

I currently read this metadata from the Python code itself. The advantages
of putting the metadata into the source code include:

- the source code is the definitive source of information about itself;
- even if the user deletes the README and CHANGELOG files, they can 
  still find the metadata;
- if your application wants to report a version number (as many apps 
  do) then it is easy for them to do so.


But the disadvantages include:

- it's a bit sad to have to put such metadata into the source code;
- the risk of the changelog getting out of date.


> I would like Python's packaging tools to have the same capability.
> 
> This requires recording the Changelog document in a machine-parseable
> format, with specified locations for each of the fields to be read for
> each version.

I wonder whether it would be better to have setup.py check the CHANGELOG and
halt if it isn't up to date? 



> I have recently gone through a process of converting the Changelog for a
> package I maintain (‘python-daemon’) to reStructuredText [0]. This has
> all the above features: machine-parseable, a well-defined way to attach
> fields to a section, etc.
> 
> [0] reStructuredText: <URL:http://docutils.sourceforge.net/rst.html>
> 
> I've now produced a small Python library which knows how to transform a
> reST Changelog to package metadata; and how to get that package metadata
> into and out of a Python distribution with Distutils.

Sounds interesting. Where can we see this?

> The result is that I will never again upload the package with a mismatch
> between what the Changelog claims is the latest version, and what the
> package metadata says.
> 
> 
> This may be generally useful to others. I'm interested to know how
> people would expect to use this. As an extension to Distutils? As a
> third-party library? Something else?

Offering it as a third-party library is a good start, but perhaps you could
discuss this on the packaging mailing list and see whether they have any
interest in it?

https://mail.python.org/mailman/listinfo/distutils-sig/


-- 
Steven