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

[Ben Finney]

Steven D'Aprano <steve+comp.lang.python at pearwood.info> writes:

> Ben Finney wrote:
> > The source has a ‘CHANGES.txt’ file which has no entry later than
> > version 0.2a. Why was the later version made, and when will the
> > change log be updated for that?
>
> Ah, I knew I forgot something!

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.


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 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.

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?

-- 
 \      “Nullius in verba” (“Take no-one's word for it”) —motto of the |
  `\                                   Royal Society, since 1663-06-30 |
_o__)                                                                  |
Ben Finney