search

psf / black

The uncompromising Python code formatter
https://black.readthedocs.io/en/stable/
MIT License
38.5k stars 2.43k forks source link

Replace CHANGES.md with something less prone to merge conflicts #2766

Open JelleZijlstra opened 2 years ago

JelleZijlstra commented 2 years ago

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:

onerandomusername commented 2 years ago

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

hauntsaninja commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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:

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:

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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: