Open JelleZijlstra opened 2 years ago
towncrier only supports rst, afaik. I haven't been able to make it work with an md template.
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.
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.
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.
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.
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:
.rst
filesBlurb 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:
changelog add
.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.
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.
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)?
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.
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 assphinx-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 toCHANGES.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:
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.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)
As @Shivansh-007 noted in https://github.com/psf/black/issues/2238#issuecomment-1010922392, 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: