[Distutils] PyPI changelog support, releases.json / common NEWS.rst format?

[Erik Bray]

On Fri, Jul 11, 2014 at 5:24 PM,  <mario at include-once.org> wrote:
> I'm currently tinkering on a freshmeat substitute. And for automating
> release announcements been looking around for common package meta
> data schemes. PyPIs /pypi/pkgname/json (or the xmlrpc interface) looks
> quite interesting. It obviously mostly targets dependency management
> and systemic categorization.
>
> So from googling around this never came up: But would it be feasible
> to include a version changelog / release summary via du.register?
>
> Of course, I'm referring to a human-readable "This version adds and
> fixes..." changelog, not the (name, version, timestamp) journal tuple.
>
> The releases{} per-URL `comment_text` seems widely unused.
> Was that its purpose?
>
>
> I hope this isn't getting too off-topic, this is -just for comparison
> and context- what I'm intending to eventually map PyPI release streams
> onto:
>    http://fossil.include-once.org/freshcode/wiki/releases.json
>
>
> There are probably other priorities for distutils / warehouse
> currently. So alternatively, is there a semi-standard for NEWS.txt
> or CHANGELOG etc. files within Python packages?
>
> Cheeseshop project homepages which also include a release notes list
> via `long_description` seem far and few between. I actually found
> just one:
>    https://pypi.python.org/pypi/py-translate
> Which seems to share a reStructuredText source for documentation and
> pypi homepage:
>    https://raw.githubusercontent.com/jjangsangy/py-translate/master/HISTORY.rst
>
> (I'd have presumed Markdown-style release notes to be favoured.)
> Anyway, is there an estimate on how many packages include release
> notes at all?

Interesting question--I've long struggled over the question of how
best to maintain a readable "human-readable" changelog/release notes.
Part of it is social, and getting all contributors to enter the
correct changelog entry for any changes they submit.  I've mostly
gotten that hammered out for my main projects.

But managing a changelog for a project with multiple release branches
is also a bit tricky and something I've been wanting to find a better
way to automate.

As for actual formats I long ago adopted the format used by
zest.releaser [1] even though I'm not using it as much any more to
make my releases.  I think the format it recognizes by default is all
valid ReST, and I've preferred to stick with that.  I also try to link
every changelog entry to a bugtracker issue number in square brackets.
So for the most part the format has been kept machine-parseable (in
fact we have a Sphinx plugin that automatically converts the "[#nnnn]"
issue number markers to links).  See for example the Astropy changelog
[2].

Still, if anyone else has further thoughts on this topic I'd be interested.

Erik


[1] https://github.com/zestsoftware/zest.releaser/blob/master/CHANGES.rst
[2] https://github.com/astropy/astropy/blob/master/CHANGES.rst