Pushed fixed to fix the links, and to add a thanks to each author.

I assume this is supposed to be the place to discuss the new changelog format?

A) Thank you, I really like that the contributers are mentioned. That's a nice and appreciates the work. I was thinking about suggesting something like that =)

But I don't think it's necessary for minor edits (say fixing a typo in the documentation). They are unmistakenly none the less important contributionss to the project, but I don't think it's worth listing individual changes in too much detail if it's just a lot of noise with little to no useful information.
I don't particularly liked the previous style to just link the milstone with label Lots of bugs fixed. It could be a bit more. Maybe a good compromise would be an entry with a conclusive list of the individual issues but without additional explanation or attribution.
It's still a question for debate what would qualify as a minor edit, but I am sure a non-essential typo in the documentation like #5300 sure does. #5318 shows an example of a code refactoring that I would categorize as minor edit. This should probably be left to the maintainer's discretion.

B) I am not sure if the entries are sorted by anything (are they?) But I think at least the breaking changes should be on top of the list.

@straight-shoota they're sorted by category, then my opinion of their importance, basically. There's only one breaking change this release, and it's within the first 5 items and has a giant bold (breaking-change) so I didn't put it right at the top.

And regarding format, ideally I'd love to write more than one line for some changes, but I think that's going too far in the realm of a blog post. The less-important changes are all far down the bottom - just stop reading when you get bored. And I like it being an exhaustive list. I don't think it's an issue. What do people think?

IMHO:

Breaking changes should be distinct, and at the top, they're the most important information.

There are too many entries listed; it's hard to skim through. Some entries could easily be grouped, e.g.:
"fixed IO#blocking and linking programs on openbsd, see #X and #Y" or just a plain "fixed formatter issues, see #X, #Y and #Z".

The "doc fixes" and "misc" sections are mostly noise. Removing them would have no impact on the changelog itself. A simple link to the milestone bugtrack (as per the previous changelog entries) for an exhaustive list of bug fixes would be more efficient (exhaustive, can be filtered, ...).

Good stuff @RX14

@straight-shoota, w.r.t. typo PRs, people should be recognized no matter what they did. The reader of the CHANGELOG is clever to think the complexity that was involved. When in doubt, add a name more than one less. To me, it also boils down to respect of the mere contribution.

Though I somewhat agree with @ysbaddaden in that small non-logic changes, like typo fixes, could be grouped like

• Various documentation fixes (Thanks @One, @Two, @Three, ...)

(^ Only using backticks to avoid paging random people on Github for sake of example)

Breaking changes should be distinct, and at the top, they're the most important information.

Absolutely agree.

@RX14 The changelog does not just consist of the current section but it compiles to a long document with thousands of entries. So you can't just "stop reading" when your scanning through the entire file. I think it would be very helpful to have this list as consise and significant as possible.
My suggestion for this would be to contract multiple entries with minor edits into one. This could also include contributer mention as suggested by @Papierkorb but IMHO it doesn't need to.

For example, these lines

# Documentation fixes

* Fix typos in documentation. (#5253, thanks @arcage)
* Remove bad example in property? macro documentation. (#5296, thanks @icyleaf)
* Fix typo in Crystal::Macros::MacroId documentation. (#5300, thanks @straight-shoota)
* Fix typo in IO documentation. (#5322, thanks @bew)

Could become:

* Documentation: Fix several typos, remove bad example (#5253, thanks @arcage) (#5296, thanks @icyleaf) (#5296, thanks @icyleaf) (#5300, thanks @straight-shoota)

It contains all the information except the exact location of the fix (which is insignificant) but is much more condensed.

This is similarly true for the Misc section. Only #5217 should be noted specifically because it contains a significant change which could break existing tool integrations using make doc (maybe it should even be labeled as breaking-change?).

I actually disagree that breaking changes should be in their own section. They should be very obvious but I think (breaking-change) is more than enough as long as they're near the top.

I'm fine condensing some related changes into single lines but I think this changelog should be exhaustive. It should link to every PR merged in the time period.

@straight-shoota I don't understand why you want the changelog to be small. If you want to only give the important changes in the release, we can make a blog post describing the new 0.24.1 and 0.24.0 releases in much more detail and with much more editorial discretion.

I agree on linking to every PR and it is probably fine to have breaking changes standing out but not necessarily on the very top. If the changes are sorted by importance, this should be okay and breaking changes will naturally be relatively high. 👍

I want to avoid unnecessary clutter and I think it is completely irrelevant in which type's documentation there is a typo fix that adds a missing 'r'.

I've changed my mind. You really don't save much space by removing these lines. Why not keep it simple: 1 commit = 1 line? People's contributions are not "clutter", no matter how small.

The primary purpose of a changelog is documenting the development of the software, not keeping track of individual contributions. Each entry should describe a specific logical change to the codebase. 1 commit = 1 line does not fit for this because change and commit (or rather PR) are on different conceptual levels and not directly related. A single entry can easily contain references to multiple PRs each implementing a part of that change (there are three instances of this in this PR and further evidences in previous releases). Theoretically, one PR might introduce multiple changes in the sense of a changelog-entry though it won't happen very often because PRs should be focused on a single feature.

"Fixing typos in documentation" should be considered as one logical change. From the perspective of a changelog, it doesn't matter if it happened in multiple commits.

@straight-shoota I agree, one commit = one line was a bad way to describe it: one change = one line is much better. However I argue that the documentation fixes are separate changes. It's bikeshedding either way, and the impact of any decision will be minimal at best. So I'll collapse the documentation changes. I don't think the formatter or doc tool changes should be collapsed though, since each change can have an impact on people's codebase by itself.

I condensed code refactors and doc fixes into single lines, and added some new commits merged since I made this PR.

I would really love to release this before the end of the week and get 0.24.1 out before christmas. The current state of 0.24.0 is half-release, half-prerelease and everyone is confused. We need to release 0.24.1 and get everyone on the same version of crystal again. Plus we have the LLVM version upgraded so that we can use --release without --no-debug again if we release 0.24.1.

I'm using 0.24.1 for a month +/- now, no major issues were found, tested with multiple big community shards. You got an OK from me.

@mverzilli any word on the binary builds of the new release? Any help that can we provide?

Thank you.

Hi @luislavena! We're working on it. The plan is to start using this at least for linux x64 packages: https://github.com/crystal-lang/distribution-scripts

However, those scripts depend on @ysbaddaden's Alpine package, so we want to be sure that we can reproduce the whole release process with this new approach. That's where we are at. As soon as we manage to generate packages in a way that we feel confident we can repeat for 0.25, we'll release. Our current ETA is in a few days, maybe one week (original goal was before the end of this week, we're striving to make it might slip to next week).

Very excited to see the new efforts for transparency! Can I ask why 0.24.1 has two different tags?

Can I ask why 0.24.1 has two different tags?

Because we want to switch to v#.##.# tag naming, but we'll do this incrementally so we will have both for a few releases.
Relevant IRC log