Changelog maintenance plan

[wshanks]

It would be good to keep a change log as changes are made instead of writing it at release time. We have CHANGES.rst now. Do we just add notes to it as we go or shall we use a release notes management system? Using a system is nice for avoiding merge conflicts and keeping the notes formatted.

The systems I know about from use in other projects are the following. They all follow the pattern of holding a directory of files with notes that get committed along with code changes and then compiling the notes into the changelog file at release time.

1. Towncrier: Most popular. Used by pytest, pip, numpy, etc.
2. Reno: From the openstack project.
3. Scriv: From the author of coverage.py and used by coverage.py.

I would go with Towncrier since it is the most popular unless there is an argument for another option. They all seem similar to me. I have more experience with Reno, but I haven't seen anything from it to make it stand out from Towncrier.

I noted the points I would put in a new release currently here: #193 (reply in thread).

[newville]

@wshanks Thanks - that sounds like a good idea to me. I have to admit to not being familiar with any of these. The READMEs of both Towncrier and Reno make it sound like each is a really valuable tool but with slightly different aims.

+1 on the concept, I defer to you on which to use.

[jagerber48]

Until we get a release notes management system I suggest (and await feedback) the idea that, prior to release, change notes are collected in an unreleased section with no version number or date populated, since we don't yet know the version number of date for the next release. Then when we make a release part of the workflow is to add the version number and release date to the changelog.

Is this changelog for users or for devs? Do we want to expose this changelog in the documentation? Or is the github releases page sufficient?