Releases
At $DAYJOB I now manage between 15-20 python libraries that implement extensions to Openstack’s Django-based dashboard, or are microservices that implement REST APIS (or both). For a while I’ve been working on adding documentation written for Sphinx in ReStructured Text. It’s taken a learning curve but I’m slowly getting the toolchain and build process going.
The next thing I wanted to tackle was maintaining a readable changelog for my current project. This weekend I started experimenting with Jeff Forcier’s Releases library. Releases is a Sphinx extension that makes it pretty easy to maintain the changelog for a python library (or anything you can write sphinx docs for). Jeff wrote Fabric, and Releases came out of his struggle with how to best maintain Fabric’s changelog. Changelogs are tricky - trying to generate one from version control can be automated but doesn’t give you control over how much information to provide about a given feature or fix, and forces commits to be written with the changelog in mind. Manually maintaining the changelog obviously gives you fine control over what to include and the language tone, but making sure that the log includes what bugs/fixes get into various releases is tedious. Jeff describes the the myriad issues involved in his original post on his solution to this thorny issue.
Enter Releases:
>Releases is a Sphinx extension designed to help you keep a source control friendly, merge friendly changelog file & turn it into useful, human readable HTML output. (from the Releases documentation)
Releases turns a file like changelog.rst into this (Fabric’s changelog).
I decided to start testing Releases out, and ran into my first bug right off: the code I’m writing has not yet had a release, and writing a changelog like this (without an actual release listed) doesn’t work:
=========
Changelog
=========
* :feature:`1` Implement REST service
* Flask-based API server
* Celery-based queue
* Documentation for Installation and API
I chatted Jeff up on Twitter and then IRC, and we decided this was not really a bug, but an edge-case he didn’t have, but was something that should be fixed. There’s now a ticket filed on Github, and I did find a workaround: adding a no-date release at the bottom fixes it (and it does not render the null release):
=========
Changelog
=========
* :feature:`1` Implement REST service
* Flask-based API server
* Celery-based queue
* Documentation for Installation and API
* :release:`0 <>`