> A changelog is a raw, engineering driven manifest of everything that has changed. This log sometimes needs more context. Okay the wizbang had a hoozit added, what the hell does this mean and why do I care? Or it needs less and a lot of the engineer rambling needs to be stripped out.
With that definition it literally is just the git log though isn't it, which was GP's point?
I know you're writing in agreement, but it sounds like your changelog is an intermediary step, and I don't understand why it's needed? To fill in the gaps from lazy commit messages?
> With that definition it literally is just the git log though isn't it
I think you're right if you go by that definition ("changelog is a raw, engineering driven manifest of everything that has changed"), but there I think there is an intermediate step between git log and the user-facing release notes, whether or not it's formalized, which is to basically squash the messages into the list of effective changes since another point-in-time (eg: last release).
Let's say you add a feature, then refactor it a bit, then fix a bug in that new code. The only thing that needs to be there is the "Added a feature" part, because the rest is meaningless noise when you compare it to the prior release.
Likewise, if you add then revert something, both can be removed.
Or if you bump a dependency to version 2.0.5, then a couple days later go to 2.0.6, you don't need to mention the 2.0.5 one at all.
For me personally, this is just part of the process of how I go from git history and PRs to actual user-facing release notes (that have "why", context, and are sorted by added vs fixed, and have callouts of deprecations or breaking changes). But there's a case for it being its own output, or even the only output.
>I know you're writing in agreement, but it sounds like your changelog is an intermediary step, and I don't understand why it's needed? To fill in the gaps from lazy commit messages?
It's about the audience.
* Commit Messages - These are comments that last for the life of the project. The audience in for engineers far in the future and it should explain what changed, why and the context
* Pull Request Message - These are comments that live for a short time and are targeted for reviewers. Things you might cover here that aren't covered in a commit message is what kind of manual tests were done, releases you want to target, or reference other PRs that might be related
* Changelog entry - These audience here is internal. It is SREs, release managers and the authors of the release notes
* Release notes - This is for the customers
For many changes, all of these can be the exact same thing. It's one reason why I like conventional commits. In those cases you can write it once and it shows up everywhere with very little friction. You add it to the commit message, then when you open the PR the title and body are populated from the commit. When you generate changelogs, it is pulled from git history. Engineering isn't always the happy path, for special situations in each one of those steps you can edit it and add or remove context for the particular audience.
Not all orgs need this or need to care about it. It's completely okay if they don't. I've just found it useful in mine.
When using open source tools, I love having a change log with direct links to merge requests and issues, and potentially across several repositories. It makes the process of reviewing and searching for changes so much easier than pulling the log.
It's also great to ship that changelog with the artifacts so they are readable on third-parties (Helm Charts on Artifacthub, GitLab and GitHub releases, ...).
With that definition it literally is just the git log though isn't it, which was GP's point?
I know you're writing in agreement, but it sounds like your changelog is an intermediary step, and I don't understand why it's needed? To fill in the gaps from lazy commit messages?