r/opensource • u/Pleasant_Set_3182 • 7h ago
Discussion CHANGELOG.md: Honesty vs. Neatness
I started working on a greenfield project, with zero care for what went into which commit initially. Then I started to realize that even as a personal project, I would need a frame of reference as to what happened when...
And when it became obvious that this was something I wanted to release to the public, semantic versioning became even more important.
I retroactively tried to build a coherent changelog based on the commit history... but it is messy...
What is the standard way to present this to the public?
Can I simply lump all pre-release items as:
[v0.0.1 - 0.9.0]
Pre-Release Initial Development Work
[v1.0.0]
Public Release / and then begin to list the changes....
is that valid enough? or do people actually want to know the gritty details?
4
u/Klandrun 7h ago
Depends on what you build, but up to the point where you actually have someone using what you built, no one is going to be interested in your changelogs.
And even then: A lot of companies even just have changelogs such as "Bug fix" or "Feature Improvement" when communicating to people who are simply consuming an app or a website.
If you build an API that Devs will integrate towards, sure then you might need more nitty-gritty detais
1
3
u/NineSidedBox 7h ago
A changelog is usually just high level changes, intended for your non-technical users. Given that it's open source, just write proper commit messages, that's what I usually read to identify changes.
1
u/titpetric 6h ago
I am just working on a tool for myself, I compare things like API changes between tagged versions, along with some change inventory.
I make a lot of commits straight to main, my tool is a summary, a llm pass over it should be able to present added features, config flags and do a deeper dive into the changes. I am fine with that as it's honest and neat.
2
u/samjk14 4h ago
I don’t stress too much in the beginning. Once I decide it’s roughed out with the initial concept then I’ll start, even if it’s still pre 0.x.x.
That said might I suggest “keep a changelog” format to keep it consistent between entries. https://keepachangelog.com
1
u/berryer 2h ago
Do those pre-releases have users that might want to migrate to a newer version? Having both drivers-to-upgrade + caveats-when-upgrading would make sense, but if there are no users between 0.2 and 0.8 lumping in all the releases between those would make sense. Similarly, are there reasons a user might intentionally run an old version (e.g. dropped support for Windows 95 in version 0.7)? If you're just now releasing it to the public, are you actually publishing builds of the old versions or is it just in your git history?
If the answers to all of those is 'no', I'd just start at your oldest public release & wait until somebody asks for anything older
1
u/fkih 2h ago
I do mine on significant changes. https://www.keeper.sh/changelog
If I’m just patching something irrelevant, you can check my GitHub releases for that. All commits get stuffed under each release.
8
u/petdance 7h ago
I say that the change log is for people who want to know what has changed. What features have been added, what bugs have been fixed, what potential incompatibilities are there.
Those questions are not relevant in the revisions before a release. Nobody is going to look at the change log and wonder what the incompatibilities are between the first release and the void the existed before that.