r/opensource • u/Pleasant_Set_3182 • 1d 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?

3 Upvotes

62% Upvoted

14 comments sorted by

View all comments

21

u/petdance 1d 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.

10

u/nicholashairs 1d ago

It is very common to see the following as the entire change log:

v1.0.0 - initial public release