Skip to content

initial changelog #230

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

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

initial changelog #230

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b75d976
initial changelog
vivus-ignis Oct 21, 2025
667470a
added authors
vivus-ignis Oct 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 52 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This file should be generated automatically if we do not or want to additionally use GitHub release pages and the version changelog integrated there. Manual writing of the file is error prone and inefficient.

Copy link
Contributor

@yeoldegrove yeoldegrove Oct 22, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I second the auto generation of changelogs. This is very simple with github tooling and e.g. GLRD already does this:
https://github.com/gardenlinux/glrd/blob/fdba74c24ddd2b7eb81c49df8ab94a0f2c7d7751/.github/workflows/image-release.yml#L73-L86

The changelog itself it not the problem we currently have but the version publishing process is. Currently this is error-prone and manual as we have to manually define version strings in multiple files (correct me if I am wrong).

Again GLRD as an example does not hard-code versions anywhere but uses dynamic versioning, based on a pushed tag:
https://github.com/gardenlinux/glrd/blob/fdba74c24ddd2b7eb81c49df8ab94a0f2c7d7751/pyproject.toml#L33-L38
The pushing of a tag triggers, python package build and image build (used to consume as github action) and generation of release notes. Adapting the release notes and adding e.g. breaking changes is currently manually. I am pretty sure this could be combined with some automatism to read user defined release note input, e.g. a file as @vivus-ignis suggested (or just done in this way).

I would like to see a concept before implementing something.

Copy link
Contributor

@NotTheEvilOne NotTheEvilOne Oct 22, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was thinking of tools like git-changelog. It basically requires a bit higher quality commit messages to generate a changelog (release notes) including "breaking changes" and other important information automatically out of it.

The information purely relies on the author and committer both hopefully knowing best what has been changed for which reason and what the implications are. Commit messages should be self-contained and therefore everyone reading a commit message should know what this commit does, why it is needed and what may break in the process. All upper level tooling like GitHub PRs are only build on top of this basic concept.

Please consider that a Git repository can be moved to another service provider. Git messages are here to stay, that may not be true for tools build on top of it (like PRs).

changelog.md files are some kind of bridges to the old world of hosting a web page for a project and manually announcing releases. It is useful for certain projects but contains a burden of maintaining it. And no, a changelog should not contain the whole history of the project since 1970 AD. As we have GitHub releases at hand I would personally say we don't need the file at all. The generated content should go to a GitHub pre-release and reviewed there before release.

Copy link
Contributor Author

@vivus-ignis vivus-ignis Oct 22, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was thinking of tools like git-changelog. It basically requires a bit higher quality commit messages to generate a changelog (release notes) including "breaking changes" and other important information automatically out of it.

The information purely relies on the author and committer both hopefully knowing best what has been changed for which reason and what the implications are. Commit messages should be self-contained and therefore everyone reading a commit message should know what this commit does, why it is needed and what may break in the process. All upper level tooling like GitHub PRs are only build on top of this basic concept.

Please consider that a Git repository can be moved to another service provider. Git messages are here to stay, that may not be true for tools build on top of it (like PRs).

changelog.md files are some kind of bridges to the old world of hosting a web page for a project and manually announcing releases. It is useful for certain projects but contains a burden of maintaining it. And no, a changelog should not contain the whole history of the project since 1970 AD. As we have GitHub releases at hand I would personally say we don't need the file at all. The generated content should go to a GitHub pre-release and reviewed there before release.

Your suggestion unfortunately has a bunch of "ifs". If commit messages are self-contained, if they are equally important etc. Yes, curated changelog means additional work, just like documentation and examples that have to be kept in sync with the code changes.

And this is the whole point: manual process (or tools-assisted, but still curated by a human) is the work done by humans for humans. Even if we pretend this library is not a public product, it's a public repository and it has users (our team at the very least).

Curated changelog is not a sign of an "old world" just like books are not outdated in the times of TikTok and GenAI. Because tools are not able to bring meaning.

Copy link
Contributor

@NotTheEvilOne NotTheEvilOne Oct 22, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We may both @vivus-ignis think of a similar solution but different responsibilities and maybe misunderstanding of if changelogs are useful at all.

Yes, changelogs are useful and we should be able to document what has changed and especially what breaking changes are in a new release.

I would like to move the burden of "curated changelog entries" to the author itself. He should know best what he has done in a certain commit and why. If a PR for this project has no meaningful commit messages meaning a tool can read them it will be simply not be accepted in that form.

Then the commit history is parsed by tooling to generate a "changelog" (of any meaning in this discussion). It is not automatically accepted or ignored afterwards. It should be read by a human (for humans ;)) to remove duplicates and commit messages that are reverted afterwards if not detected by a tool. Meaningless commits are also removed from the list by the way, because "code cleanup" will be required in the future but does not really bring additional value to the public audience.

And than the changelog (or release notes) are published (again, in any meaning in this discussion).

I think we will have another interesting discussion about that and may find a conclusion we'll document and maybe even adapt in this PR later :)

Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# Changelog

> [!TIP]
> Changelog format guideline: https://common-changelog.org

## [0.11.0]

### Added

- Semver support for the release notes generation code ([219](https://github.com/gardenlinux/python-gardenlinux-lib/pull/219)) (vivus-ignis, ByteOtter)

### Changed

- Update GLVD URL ([226](https://github.com/gardenlinux/python-gardenlinux-lib/pull/226)) (vivus-ignis)

## [0.10.2] - 2025-10-17

### Fixed

- Explicitly set `make_latest` value for github release creation JSON payload in `create_github_release` function (nkraetzschmar)

## [0.10.1] - 2025-10-17

### Added

- gl-gh script for creating Github releases ([222](https://github.com/gardenlinux/python-gardenlinux-lib/pull/222)) (vivus-ignis)
- Github release notes generation code ([202](https://github.com/gardenlinux/python-gardenlinux-lib/pull/202), [198](https://github.com/gardenlinux/python-gardenlinux-lib/pull/198), [217](https://github.com/gardenlinux/python-gardenlinux-lib/pull/217), [206](https://github.com/gardenlinux/python-gardenlinux-lib/pull/206)) (vivus-ignis)
- Support for reading metadata files, especially feature sets and platforms, without parsing data from the features directory ([172](https://github.com/gardenlinux/python-gardenlinux-lib/pull/172)) (NotTheEvilOne)

### Changed

- New dependency: `gitpython`
- Improve type annotations in apt module ([201](https://github.com/gardenlinux/python-gardenlinux-lib/pull/201)) (ByteOtter)
- Improve type annotations in git module ([203](https://github.com/gardenlinux/python-gardenlinux-lib/pull/203)) (ByteOtter)
- Improve type annotations in s3 module ([204](https://github.com/gardenlinux/python-gardenlinux-lib/pull/204)) (ByteOtter)

### Changed (dev setup)

- Improve configuration for local linting and code coverage generation
- New dev dependencies: `isort`, `requests-mock`, `pyright`

## [0.10.0] - 2025-09-16

### Added

- Code for artifacts upload to github release page ([191](https://github.com/gardenlinux/python-gardenlinux-lib/pull/191)) (vivus-ignis)
- Add support to additionally tag an existing OCI manifest ([176](https://github.com/gardenlinux/python-gardenlinux-lib/pull/176)) (NotTheEvilOne)

### Changed

- Python dependencies update
- Replace GitPython implementation with pygit2 one ([187](https://github.com/gardenlinux/python-gardenlinux-lib/pull/187)) (NotTheEvilOne)
Loading