Create a changelog

[joshka]

• Add git cliff default config
• Configure git-cliff to align with commit history
• Create CHANGELOG with git cliff

When diagnosing a break due to 0.1.13 just now, I noticed that there is no changelog, which makes it more difficult to search for which particular change caused the problem

This is a stub of a changelog config using git-cliff.. Please consider using it to generate your changelogs. These will show up automatically in dependabot PRs, which is pretty nice for crate users.

[Manishearth]

I don't really like autogenerated changelogs and I do not have the time to put into this project to do this well. I basically inherited this project and am happy to keep it maintained but do not intend to put more effort into it. Thanks.

[joshka]

Isn't something better than nothing? If you're unable to keep this maintained at a basic level like this, please consider adding another maintainer that can.

[Manishearth]

People who want such a log can look at the git logs, I am careful about correctly tagging releases. This type of log is not much better than that: it's a little bit more accessible, but I don't think it's worth it.

I think the "something" here is extremely low quality, and not much better than the existing use of git tags. It's not "nothing".

[joshka]

People who want such a log can look at the git logs, I am careful about correctly tagging releases. This type of log is not much better than that: it's a little bit more accessible, but I don't think it's worth it.

This is an O(n) approach to an O(1) problem

I think the "something" here is extremely low quality, and not much better than the existing use of git tags. It's not "nothing".

Quality can be improved - update the config, write better commit messages, squash commits instead of using merges, and ensure that squashed commit messages actually explains the change well enough to communicate this in the changelog. Automated changelogs reduce your maintenance burden. This is notable particularly on a repo that you seem to have stated that you don't want to invest effort maintaining (despite 100s of millions of downloads). Please forgive my incredulous reaction here, but you're absolutely wrong that not having a changelog is worse here.

[Manishearth]

This is an O(n) approach to an O(1) problem

I don't understand.

squash commits instead of using merges

aha I understand now. I wasn't aware this repo wasn't using squash commits. I maintain a lot of repos that use varying strategies here and these days I have largely been working with ones with squash commits. I have mixed opinions on squash commit workflows but in the case of this repo I think it would make a lot of sense to switch. We haven't been keeping spic and span PR commit histories. I fixed it now.

I think because this PR focused on a solution rather than the core problem you were facing we didn't really drill deeply into what about trawling through the logs was a challenge.

I greatly prefer using squash commits over having an automated changelog: I have almost never found automated changelogs to be useful, myself, they always end up feeling like a red herring and I go look at the git logs instead where I have more tools at my disposal.

Please forgive my incredulous reaction here, but you're absolutely wrong that not having a changelog is worse here.

tip: if you're having an incredulous reaction, perhaps consider that the other person has missed something (or genuinely has a different background and makes different conclusions based on that) and communicating with empathy instead of being super demanding and patronizing. like seriously, I get that your tests broke and this was frustrating, but you have been super demanding here and I don't really need to deal with this.

[joshka]

tip: if you're having an incredulous reaction, perhaps consider that the other person has missed something (or genuinely has a different background and makes different conclusions based on that) and communicating with empathy instead of being super demanding and patronizing. like seriously, I get that your tests broke and this was frustrating, but you have been super demanding here and I don't really need to deal with this.

Fair call - apologies for my tone here. I was being a jerk and that was uncalled for. I want to make sure that I express my gratitude for you working on this crate. I appreciate your work regardless of this disagreement. I'm not too frustrated about the break - that sort of thing happens. My frustration stems entirely from having issues/PRs that highlight pain points closed as effectively WONTFIX, without any real discussion (although that discussion continues on in the closed issues).

This is an O(n) approach to an O(1) problem

I don't understand.

v0.1.12...v0.1.13 has a list of the commits that are changed between versions. In order to determine which one is relevant, you have to expand each, or click through to each PR. Finding a relevant PR that introduced this change is O(n) where n is the number of commits.

The equivalent search in a circumstance where the PRs are squashed and a changelog friendly commit message is added as part of that squash is hitting find on a single document and searching for e.g. \0 or \u{1} (the former was relevant, not sure whether the latter would have helped)

Our approach in Ratatui is:

• When writing a PR, make sure the PR first comment looks contains all the necessary info to be included in the changelog
• Squash merge and use the PR comment as the commit message in the git history.
• Github automatically adds a PR number to the commit title
• Git cliff transforms the PR number into an actual link back to the commit
• We use conventional commits which allows us to automatically sort the changelog a bit better, exclude certain types of commits and highlight breaking changes more easily

Downsides for not taking this approach:

• You have to spend time to write a changelog manually
• PR numbers in commits are only shown as links when on the github site (not locally)
• Dependabot PRs are less useful to a consumer of the library - compare chore(deps): bump the cargo-dependencies group with 3 updates ratatui/crates-tui#66 vs chore(deps): update rstest requirement from 0.19.0 to 0.21.0 ratatui/ratatui#1163
• Breakages require more investigation. For context, my investigation path when looking at the break that suggested this was:
  • our tests are breaking in CI, but not locally
  • what's new in our deps - nothing
  • try to repro locally - no repro
  • realize that perhaps there's a cargo update that is incompatible and the CI is pulling that, run cargo update locally
  • notice that unicode-width went from 0.1.12 to 0.1.13 and that the tests were around zero-width handling
  • open up unicode-width repo
  • look for changelog file - none
  • look at the release tag - no release notes
  • look at the release diff - 32 commits, and the only one mentioning zero was not relevant - width would have found the right one, but the entire library is about width, so 🤷
  • pinned the dep to 0.1.12 to make an investigation into why this was broke our tests later (and raised the issues / PRs here regarding the break, need for a changelog and need for release automation that would produce the changelog and release notes)

I'm curious if that's a path you generally would take in investigating a library breaking your code, or if you skip some of those steps?

[Manishearth]

although that discussion continues on in the closed issues

Yeah, that's typically how this goes.

I'm curious if that's a path you generally would take in investigating a library breaking your code, or if you skip some of those steps?

I generally look at the changelog, but if it's autogenerated I almost always just use git log --first-parent instead, since I can do more custom filters there. Or I click through blame history of the relevant APIs if the breakage is of this kind.

I have literally never found an autogenerated changelog to be more useful than just git log. I love manual changelogs but not every crate I maintain has them since I can't devote that time to them all.

[orhun]

Hey, I wanted to chime in to this discussion (I'm the creator of git-cliff & also maintaining the Ratatui crate along with @joshka).

First of all, thanks for taking time to share your opinions on automated changelogs and this specific case.

I have literally never found an autogenerated changelog to be more useful than just git log. I love manual changelogs but not every crate I maintain has them since I can't devote that time to them all.

I personally have multiple projects that I maintain too. More specifically, each one has a different structure, commit styles and so on. It was a deliberate choice that I made to push myself to try/learn new things each time. But then... releasing each project properly started to take a lot of time. That's why I created git-cliff, to save myself from writing the changelog manually or using something like git log which has less verbosity.

So you won't actually devote more time to the projects that you maintain this way, you only need to set up your config once like in this PR. In the long term this will save you time from replying to issues like #55 across your projects because the changes will be more clear and users won't have to dig in N layers trying to find out what's wrong with their tests.

I think changelog/release automation will be an overall positive addition for this project. I'd be happy to see that and also happy to help with setting it up as well.

[Manishearth]

Thanks for the suggestion, but I think I'll stick to my position of automated changelogs being worse than a squashed git log. I'm glad your tools work for you, but this is not something I'd ever really use on my projects. The projects where I maintain a changelog I prefer to actually build a good one by hand (or, in the case of clippy, we have CI enforcing that PRs contain their changelog entry so it's mostly just a quick script to generate the log).

And as previously stated I don't like autopublish automation, for a variety of reasons. Again, happy it works for other people, it really doesn't work for me. So far the process of actually making a release has not taken any significant time for me for most of my projects, and on ones where it does take time it's finicky enough that autopublish automation would not work and likely be somewhat dangerous.

In the long term this will save you time from replying to issues like #55 across your projects because the changes will be more clear and users won't have to dig in N layers trying to find out what's wrong with their tests.

eh, it's not that much time taken, and this happens extremely rarely (and when it does I'd prefer to know about it). The attitude they approached the discussions here with were a bigger problem than the fact that I sank time into this: I just don't really want to spend time engaging with that. But the misunderstandings were rectified and it's fine now.