Repository navigation
Create CHANGELOG file #229
Description
What would you like to be added:
CHANGELOG should track changes to the library
Why is this needed:
Tracking changes without reliance on github-specific infrastructure like github releases is a portable way to communicate updates to the library.
Metadata
Metadata
Assignees
Labels
No labels
Activity
yeoldegrove commentedon Nov 5, 2025
Following the discussions we already had in #230 let me sum up my perspective.
TLDR: I would start by codifying and documenting the release workflow (version bump, [approval], tagging, release generation, notes generation), then layer human-curated highlights on top.
While I am very much in favor of tackling the topic of having a changelog, I think we should approach it a bit broader and from another end.
We should document a clear release process first (or in parallel), otherwise a standalone CHANGELOG file risks drifting from how releases actually happen.
Today there is no documented release process for python-gardenlinux-lib, so step one is to define/agree it.
Most of the other Garden Linux projects use GitHub Releases as the canonical changelog; this library should align for consistency.
GitHub Releases can auto-generate notes so no commits are accidentally omitted (a risk with hand-written files).
The release-notes can be templated and we add sections (Added/Changed/Fixed/Breaking) to match common-changelog style. We could even think about creating those sections from commit messages (would need to introduce some "tags").
The release process should include a mandatory “breaking changes” step so humans must summarize impact, even if notes are auto-generated.
Maintaining a CHANGELOG.md file adds extra manual work and is likely to be rushed or forgotten during urgent releases. Using GitHub Releases avoids duplication between a file and the release page, preventing divergence and confusion.
Auto-generated releases provide an immutable audit trail and timeline without extra commits just to update a file.