Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Changelog file grows too large #15609

Closed
straight-shoota opened this issue Mar 27, 2025 · 3 comments · Fixed by #15627
Closed

Changelog file grows too large #15609

straight-shoota opened this issue Mar 27, 2025 · 3 comments · Fixed by #15627
Labels
status:discussion topic:infrastructure

Comments

@straight-shoota
Copy link
Member

straight-shoota commented Mar 27, 2025 •
edited
Loading

CHANGELOG.md has reached a size where GitHub struggles with rendering a preview (e.g. https://github.com/crystal-lang/crystal/blob/changelog/1.16.0/CHANGELOG.md fails with "This blob took too long to generate.").
I'm not sure what's the exact threshold for that, but it's clear that such a large file is impractical in many ways. And it's ever only growing, on average ~25 kB (or ~300 loc) on every release.

We've been there before at #12897 (comment). At that time, we cut off all older changes before 1.0 and moved them to CHANGELOG.0.md in #12898. But this was only a temporary fix. The current CHANGELOG.md has already outgrown the pre-1.0 changelog.

I believe it probably makes sense to break out the current changelog, i.e. the changes since the last release. That's the relevant stuff which is actively worked on.
All the changes from older releases are just an archive.

We could consider keeping just a CHANGELOG.md with changes since last release in each branch. Every release branch contains its changes from the previous one. You could get the full changelog by concatenating the CHANGELOG.md files from all release/* branches.

I think there's good value in having a compiled version of the entire changelog, though. But I suppose that could be provided out of tree, for example on the website (for example: https://curl.se/changes.html).
@straight-shoota
Copy link
Member Author

It seems rather straightforward to let CHANGELOG.md only contain the current changes, i.e. the entries since the last minor version.

I'm interested in opinions whether we should keep the full changelog in tree. For example, that could be a CHANGELOG.old.md. Or, following the pattern of the existing CHANGELOG.0.md for changes before 1.0, we could have one archive file for each major version. That would mean the current CHANGELOG.md would be moved to CHANGELOG.1.md.
Having one file per major version could create some noise if we ever get to a faster pace on major releases (you never know 🤷), but for the foreseeable future this shouldn't be an issue. We could also consider moving the files to a directory in docs/.

@Sija
Copy link
Contributor

Sija commented Apr 1, 2025

I'd propose splitting the changelog per minor versions into a doc folder, in a pattern along the lines of doc/changelog/1.16.md. Logic required to keep it up-to-date for each patch version would be needed, yet from the user perspective IMO it seems pretty clean.

@Blacksmoke16
Copy link
Member

Blacksmoke16 commented Apr 1, 2025 •
edited
Loading

Random assortment of ideas I've had:

  • Split by year like esbuild
    • Too many files in repo root
  • Split by major version like node
    • Doesn't solve our problem
  • Split by minor version like terraform
    • My personal fav, expanded move on below.
    • For us probably fine to show last released version instead of yet-to-be released version
  • Drop the changelog file in favor of GH release notes like ruby
    • Not a fan of losing this history if we ever migrate away from GH
  • Have the changelog file just contain a link to the crystal book page that an have the full changelog as static HTML
    • Decent option as a place to at least have a full list
  • TBD

I personally think terraform's approach is the best. The root changelog file still exists to see changes in the latest version, easy links to older releases, that in tern link to older releases, and so on. I also rather each feature version branch having its own more focused changelog than some non-standard place that is just going to be bloated with files over time. Esp given we keep a release/xx.xx branch around for them all.

This does mean there isn't a "see changes from all releases in one place", but probably be easy enough to render the markdown into the book or something to handle that?

@straight-shoota straight-shoota mentioned this issue Apr 2, 2025
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
status:discussion topic:infrastructure
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Trim CHANGELOG.md straight-shoota/crystal
3 participants
@Sija @straight-shoota @Blacksmoke16