RFE: Use a changelog tool instead of 'CHANGES'

[stephenfin]

I've been looking at integrating reno for the Sphinx documentation, instead of the monolithic CHANGES file. The way we do our stable branches, as discussed in #4398 and #4211, means we can't currently use this tool (more discussion here).

I'm yet to evaluate towncrier and other solutions. However, I'd like thoughts on moving to a system like this. The main advantage would be more detailed, informative changelogs, however, it would also allow us to make release notes part of the requirements to add a change without having to worry about merge conflicts. This would prevent the need for maintainers to have to do this after the fact, which would in turn mean there's one less reason not to use protected branches.

Thoughts?

[jfbu]

I have had occasion to fix CHANGES entries a posteriori. Currently it is indeed better if PRs do not include a CHANGES entry and maintainers add it after merging. This does not work badly and details of merged PRs can be found on the github site.

As as side remark, commit messages are not always much detailed, from what little experience observing Sphinx development over the last two years I have gotten. Often neither CHANGES nor commit messages provide not much detailed information. I think documentation of Sphinx is already very big, (I don't think I have yet found the time to read it entirely), and switching CHANGES model is not priority from point of view of Sphinx user.

Maintaining detailed release notes looks like adding a layer of extra work to a project which has few maintainers. Same for maintaining past branches and backporting patches to previous major series. (I am really assuming the role of the anti-innovation guy here ;-) )

[stephenfin]

To be clear, a tool like reno does not use git commit messages - it uses specific files included as part of the release. See here for example. Ditto for towncrier.

The main reason I was looking for this is to prevent merge conflicts. This is a reason I don't currently make modifications to CHANGES myself (I don't want to have to babysit my PR 😄). This would allow us to use protected branches for master and stable.

(I am really assuming the role of the anti-innovation guy here ;-) )

😄 Nope, you're assuming the role of someone who does this stuff regularly. These tools work well for my projects, but that doesn't mean they're suitable for everywhere. It's good to get this kind feedback.

[jfbu]

My message was confused, but deep inside I had understood that reno did not use commit messages (I admit not to know yet what reno is); I had at back of my mind the one bit of experience I have had with PR (for latex internationalization of the doc) on the CPython repo. I had to follow guidelines for inclusion of some blurb in news file. It was a constraint which made it more complicated for me to submit the PR, and simultaneously I felt it was very lenient because I did not have time to figure out what were the style guidelines so I just did it my way emulating other entries. It would have been much better if it had been the duty of the maintainer responsible for merging (perhaps, one day) my PR to add a to the point news file entry, with proper lexical styling.

[shimizukawa]

As a case, major projects such as pip (pypa/pip#4346) and tox (tox-dev/tox#615) are introducing towncrier. I believe that towncrier has the potential to become a de facto standard in the future. However, IMO, it is doubtful whether it matches the current Sphinx development team. At least not now.

[stephenfin]

Closing this per the comment from @shimizukawa above. We can change this in the future if necessary