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 -- https://mail.python.org/mailman/listinfo/python-list
