Replace CHANGES.md with something less prone to merge conflicts

[JelleZijlstra]

As @Shivansh-007 noted in #2238 (comment), our current CHANGES.md mechanism for the changelog is very prone to merge conflicts. Another problem is that when a release happens between the time a PR is opened and when it is merged, it's possible to have the changelog entry go into the wrong section.

I haven't looked in detail in this space, but I know that possibilities include:

• towncrier
• blurb, which is used by CPython
• writing our own; I'd like to avoid that unless we really have unusual needs that existing tools can't support

[onerandomusername]

towncrier only supports rst, afaik. I haven't been able to make it work with an md template.

[hauntsaninja]

I've never really liked towncrier, blurb or their ilk. The dumb solution is to just add a bunch of bullet points with a note saying "please fill in a random bullet point". When you release, remove the empty ones.

[cooperlees]

I think the simplicity of what we have to ensure we get change log entries far outweighs the complexity of all alternatives and make release time much easier on the releaser.

To be fair too, these have to be the easiest merge conflicts in the universe to fix and deal with compared to source code. It’s a list of sentences.

[ichard26]

I'm open to using towncrier assuming if I can get it to handle Markdown reasonably well and the amount of code necessary to integrate it isn't that high. Note if I do bring over towncrier I'd probably also bring over the changelog update automation that pip (I consider its changelog to be very nice and I'd like to model it if we do choose a more advanced changelog solution).

Except! ... @hauntsaninja's solution is also pretty appealing to me as well, though I'd make the modification to introduce some more sectioning of our entries grouping bug fixes, enhancements, etc. separately. Adding sections would also have the nice side-effect of making merge conflicts less likely as all of the changelog additions aren't concentrated at the end of the list causing all of these conflicts.

I am indeed a bit wary of adding more complexity to this domain.

[felix-hilden]

Cooper's right about the conflict difficulty, and that might tip the scale if we're thinking about complex changes. At least our only problem now is conflicts, instead of some tool not working as intended. And while I dislike the messiness of filling in random bullet points, sections could indeed ease the pain. Now that we're going stable, would it be reasonable to introduce something like "fixed", "added", "changed" etc? Or would topical be better: "cli", "style", "integrations", "preview"...? Anyways, instead of adding them as needed, they could be removed on release if empty.

[Shivansh-007]

I've never really liked towncrier, blurb or their ilk

I agree with this here, and I have reason to say so, towncrier is a great tool but has some unusual specifics:

• No markdown support, only .rst files
• Fragment type is the file extension
• Creates new changelogs for every release, there is no way to maintain a single main changelog containing all version release changelogs
• You can't have two changelogs for a single PR (according to their naming method)
• It is somewhat dead, last twisted/towncrier@0e6a479 was in September, since then, there has not been commits/responses on newly created issues.

Blurb is built for CPython development, specific to their workflow: issue numbers from bugs.python.org, only .rst files, so we can't use it anyways.

I think the simplicity of what we have to ensure we get change log entries far outweighs the complexity of all alternatives and make release time much easier on the release.

I don't understand this, introducing something like towncrier/changelog feature I am building at discord-modmail (like discussed on discord) would make the process much simpler. The basic changelog creation process would be:

• Running a changelog create command, say changelog add.
• It would prompt you for the change category and the GitHub PR number (validate them).
• Then it would open your desired editor (you have configured) and ask you to write your changelog.

For release, you just need to run one command changelog release 1.0.0 and boom, there you go.

To be fair too, these have to be the easiest merge conflicts in the universe to fix and deal with compared to source code. It’s a list of sentences.

Yes, you are right, but on every push? It becomes annoying. And I don't think GitHub has ever been kind enough and fixed those merge conflicts for me.

[ichard26]

I suspect what Cooper is mentioning is that currently the release process can be fully done through the web interface. Unless we add even more complexity to the release workflows to automatically run this tool, this will require the use of the command line. This personally doesn't bother me but some people do like very lightweight release procesees.

[cooperlees]

My goal is not necessarily to prioritize releasing from the web interface, but to have as little manual human tool running as possible for a release. This reduces the room for human error. Today we have 1 commit and a GitHub release cut (which can be done via API, CLI or Web).

I feel all the other Change Log "automation and tooling" introduces more room for human error, compared to what we have today. A releaser today should proof read and cleanup change logs if needed as well.

I do agree tho, if a really old PR is merged it could be inserted into an old release. This I do not have a good answer other than we need to do better code review as maintainers and should check for this on each PR fixing it at merge time. Then this becomes a noop ...

Edit: I wonder how hard it would be to write something to check if the change is being added into a released version section of the change log (i.e. parse CHANGES.md)?

[Shivansh-007]

My goal is not necessarily to prioritize releasing from the web interface, but to have as little manual human tool running as possible for a release. This reduces the room for human error.

Making a release workflow that is run after a release is published could possibly be a solution to this. Basically, enhancing the current pypi_upload workflow to also handle changelog releases.

I feel all the other Change Log "automation and tooling" introduces more room for human error, compared to what we have today. A releaser today should proof read and cleanup change logs if needed as well.

I am not sure why you say so, but wouldn't the changelog automation be less prone to error? You don't have changelogs been placed in the wrong release, you don't have to fix any conflicts - you don't remove a changelog line by mistake, the changelog format is maintained...

Edit: I wonder how hard it would be to write something to check if the change is being added into a released version section of the change log (i.e. parse CHANGES.md)?

That would be fairly easy to implement, but it doesn't mention the original point of this issue.

[ewjoachim]

Copying my comment from #2238

In my projects, I've shifted to a different approach, where I removed the changelog from the code, but I use release-drafter to have the changelog in the GitHub releases based on the merged PR titles since the last tag, as well as sphinx-github-changelog (disclaimer: I'm the author of that tool) to have the changelog in the sphinx doc. That said, it shouldn't be hard to have GitHub actions make a PR to CHANGES.md whenever a release is published, so that people wouldn't have to bother with the changelog, but it would not add too much strain on the maintainers who cut the releases either and still end up in the released code. That said, towncrier is nice too (it's just that I always love a process where releasing the lib doesn't require commits/PRs/...)

To develop a bit:

• See an example at https://procrastinate.readthedocs.io/en/stable/changelog.html and https://github.com/procrastinate-org/procrastinate/releases
• In my repos, I completely abandoned the idea of having the changelog in the code itself, mainly because I wanted the release experience to be a single action on the maintainer side, while still having requirements for PR reviews and not pushing to master directly, so a GitHub action updating and committing the CHANGES.md at the time of the release would have been too complicated for my usecase. Though, I understand if you feel that you need such a file.
• A question though: would you need it to be committed before the tag is set or would after the tag be ok ? (I guess it would need to be there before the tag, but then it means you can't start the release process by issuing the tag or releasing the GitHub release, so it leaves only the possibility of a workflow_dispatch GitHub action that will commit, tag, make a PR and release, or maybe commit directly to master if you can figure out the appropriate permissions so that the action can commit to master)