Add CHANGELOG.md file

[not-my-profile]

We are currently using the GitHub releases page as our changelog, which I think is suboptimal because it just lists all merged PRs in the order they were merged ... which isn't relevant to users at all. Internal refactors also aren't really of interest to people who are just end-users.

I think it would make sense to introduce a CHANGELOG.md file like other projects have one, e.g:

• the Pygments changelog
• the Clippy changelog
• the Pylint changelog

All of these group changes by their kind, which I think is really helpful for users.

(Sidenote: Note that GitHub unfortunately doesn't linkify pull request mentions in .md files ... however I think ruff will eventually end up with its own website anyway where we can easily postprocess the file to linkify not only these pull request numbers but also all mentions of rules to their respective documentation (once #1467 has been implemented).)

Maintaining such a CHANGELOG.md file however obviously is additional effort for you @charliermarsh, since you'll often have to remind contributors to update the changelog and bump the Unreleased section for every release (although that could probably be automated) so it comes down to whether you think this is worth it :)

[JonathanPlasse]

You could also use towncrier.

[not-my-profile]

I think towncrier is neat but I think it would also be neat to keep our dev dependencies Rust only and towncrier is implemented in Python.

[JonathanPlasse]

I would follow keep a changelog as convention.

[not-my-profile]

I assume you refer to the "Guiding Principles" mentioned there? In that case I agree they seem reasonable :) ... I just force pushed to add the release date. Whether or not ruff follows semver isn't really relevant yet since we haven't yet reached 1.0.0.

I do think that we should have "Added rules" & "Updated rules" as groups so that e.g. an added command-line flag would be listed separately after rule-specific changes.

[JonathanPlasse]

Yes, that is what I meant.
I nitpick but I would use header 3 for Added rules, ...

[charliermarsh]

Gah, I do want a better changelog and I agree with all the arguments put forward here, but I'm hesitant to introduce another maintenance burden right now... It saves me so much time to auto-generate the release notes. Let me think on this for a bit. (Please don't feel the need to keep the current PR's changelog updated for now, don't want you to have to do all that work.)

[JonathanPlasse]

Why not beginning to do a release to auto generate the changelog then cancelling, adding it to the changelog, then doing the final release?

[not-my-profile]

I think the point here is that the GitHub changelog autogeneration isn't very good ... I think we should be able to come up with some better changelog generation system.

[JonathanPlasse]

I was thinking of using it as a base to improve upon following keep a changelog spec.

[not-my-profile]

"Keep a Changelog" is explicitly about not dumping git logs into changelog files ... dumping PR logs into changelog files wouldn't pose any improvement to the status quo as far as I'm concerned. I think we should either have a nice CHANGELOG.md or none at all.

As I said I think we should be able to come up with a system to get a nice changelog without putting all the burden on the maintainer.

[hugovk]

You can use add labels to PRs, corresponding to Keep a Changelog's categories, and GitHub will use those to group the auto-generated release notes:

• https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes#configuration-options

I'm using Release Drafter to do this (because it was available before GitHub introduced it, but they look pretty similar) and it's working smoothly. For each PR, I just need to add one of the Keep a Changelog labels. For example:

• https://github.com/hugovk/norwegianblue/releases/tag/0.8.0
• https://github.com/hugovk/norwegianblue/blob/main/.github/release-drafter.yml
• https://github.com/hugovk/norwegianblue/blob/main/.github/workflows/release-drafter.yml

I also have a workflow to make sure I remember to add one of the "changelog: X" labels (or skip):

• https://github.com/hugovk/norwegianblue/blob/main/.github/workflows/require-pr-label.yml

[not-my-profile]

Thanks Hugo! Using that GitHub feature would certainly be an improvement over the status quo, since it would let us group the changes and exclude refactors. I see two disadvantages that could probably be addressed:

1. regular contributors cannot apply labels to their own PRs, so the categorization would still have to be done by the maintainer (though I assume that could be remedied by setting up some GitHub bot)
2. the changelog entries would not be as neatly consistently formatted as proposed by this PR, with "New rules" and "Updated rules" entries always starting with <rule-name> (<rule-code>) (though I assume that could also be enforced via another GitHub workflow job)

However I think the bigger problem is that PR titles are in general written from a developer perspective to succinctly summarize the changes of a PR, while changelog entries should be written from a user perspective and complex changes can very well require more explanation than you could fit in a PR title. Not to mention that big PRs can very well introduce separate changes that should be documented in separate changelog entries.

So with that in mind I do actually think that a setup in the vain of towncrier as suggested by Jonathan would be preferable.

[JonathanPlasse]

FYI, Pyo3 uses towncrier.

[charliermarsh]

As a half measure, while we figure this out, I went ahead and categorized the PRs (and removed anything internal) from the autogenerated release notes. I know that's not perfect.

https://github.com/charliermarsh/ruff/releases/tag/v0.0.236

[not-my-profile]

While working on ruff I encountered a clippy lint span that could be improved and made my first clippy contribution: rust-lang/rust-clippy#10226

While doing so I have noticed their PULL_REQUEST_TEMPLATE.md, in particular:

We're collecting our changelog from pull request descriptions. If your PR only includes internal changes, you can just write changelog: none. Otherwise, please write a short comment explaining your change.

It's also helpful for us that the lint name is put within backticks (` `), and then encapsulated by square brackets ([]), for example:

changelog: [`lint_name`]: your change

I guess we could set up something similar ... however I think I'd prefer a tool like towncrier since I'd rather have the CI fail because of a malformed file than because of a malformed PR description, since I personally rather (force) push fixes than updating PR descriptions.

[not-my-profile]

Closing this ... the GitHub changelog has improved somewhat and there does not appear to be much interest in producing a more consistently formatted changelog as suggested by this PR.

[hugovk]

For reference, here's how release notes are auto-generated:

• https://github.com/charliermarsh/ruff/blob/main/.github/release.yml
• Configure automatically generated release notes #2341

[tony]

@not-my-profile Are you willing to reopen? I can also create a new issue

I would highly prefer a changelog + git tags - the reason why is it's very difficult to cite a range of package updates downstream, e.g. 0.270 -> 0.275. That can be conveyed in a CHANGELOG via a git tag easily.

[not-my-profile]

The GitHub changelog has been improved since I opened this PR. I agree that having an additional CHANGELOG file would be nice as well and it could probably even be automatically generated but yeah if you want that it's best for you to open a new issue for that. Note that releases are already tagged in git.

[tony]

New thread

I created a new thread at #6027

This re-initiates a recommendation for a CHANGELOG.md file. With this, downstream users could have much easier access to release notes.

If you have an opinion (affirmative or negative) in lieu of any accommodation already existing in this thread, definitely give it a vote or comment. Thank you!