The changelog, on the other hand, answers the question “why does the customer care about these changes?” It could be the same reason as why the commit exists, but the question is different. If the customer doesn’t care, maybe it doesn’t even need an entry. Maybe why they care is slightly different than the reason the commit(s) exist.
This is why I advocate for a hand-updated CHANGELOG.md. It’s a very small amount of writing that forces developers to consider how their PRs will impact customers that an auto-generator will never be able to do well.
This avoid merge hell on the CHANGELOG.md file.
Right, if you don't do something like this you can be in merge hell very quickly...
Sometimes, my Git commits can be kind of verbose (and I'll occasionally put in smartass comments).
I wouldn't dream of mining my Git logs for CHANGELOG entries.
Actually, I hand-run many things that a lot of developers automate.
Part of it is because I have control issues...
It felt kind of silly and I don't know if anyone actually looked at the changelogs, but it took 2 minutes out of my day and worked well.
Why? Every time I have asked this people say because you'll search the logs (which I have never done in my life) or because "it's good practice"
Sometimes it turned out to be a mistake in the original commit, or working around a limitation that no longer exists, other times it has saved me from re-introducing a bug that someone had spent effort fixing.
If the person still works with you, you can just ask them about it.
If they don't or you don't want to bother them, the commit message tells you what the change was and often times why to give you a better context.
All the teams I've worked on included information like feature, bug, defect, and the associated ticket number in the branch name, so you have the information at hand to go look at the ticket directly and see what requirements were needed.
Maybe it depends on the project but I've found myself doing this so often that I won't stop, it's such a small task that has given me so much benefit. If it doesn't help anyone then nothing was lost.
- written by people who were not me
- written by people who have since left the company
- the original documentation has rotted away through wiki replacements, issue tracker replacements, or being lost via people turnover or system replacement.
The result in many cases is the code is the _only_ documentation of the system behaviour, so seeing what was introduced together is important context to understanding why it is the way it is. I probably run git blame more than git commit at this point and there's a real QoL difference between the good commit messages and the "changes for ticket12345" commit messages.
git commit -m "feat: script pretty print" -m "added variables for bold, normal, and a nice blue arrow"
feat: script pretty print
added variables for bold, normal, and a nice blue arrow
According to the GNU coding standards, which have been used for decades for a large amount of the core software on a Linux system, what you should put in the changelog looks quite a lot like a good git commit log would look like[0]. And Linux currently uses the git log as the changelog, and IIRC had a similar format in the pre-git era.
> The changelog targets your users. It must answer questions like:
> "What cool new feature is in this version?"
> "Is this annoying bug fixed?"
> "Is it safe to upgrade, or do I need to adjust my code/workflow to this new version?"
To me, that sounds like what a lot of projects would call "release notes" or (per GNU) "NEWS file"[1], not the changelog.
[0] https://www.gnu.org/prep/standards/standards.html#Change-Log... [1] https://www.gnu.org/prep/standards/standards.html#NEWS-File
Well, it's a good job then that this forum is cool with blurring the subtle distinctions between technical terms that have been in use for decades, and is happy to just go with whatever mainstream definition of a word has the most traction...
...on this site for news about breaking into computer systems.
/s
* fixed thing X so that user can do Y
broke things so that another commit is needed:
* fixed X again, so that user can finally do Y (for realz this time)
This would not make a great release note.
And conventional commits are good thing to do regardless of whether you use them for release notes or not. Commit messages should be helpful and immediately obvious, too often its "fixed bug" or "finally figured out foo!", which really tell you nothing - might as well not have a message.
For instance, I retired the ChangeLog in the TXR project in 2015; commit messages continue to be in the ChangeLog format. A ChangeLog file could easily be produced from the commit messages.
Replicating that information in a file that is checked into git is silly; you're just begging for merge conflicts. Any time anyone sends you a patch, if it is not rebased to your current HEAD, you have a guaranteed conflict in the ChangeLog file.
Why do that to yourself.
> The changelog targets your users. It must answer questions like:
> "What cool new feature is in this version?"
> "Is this annoying bug fixed?"
> "Is it safe to upgrade, or do I need to adjust my code/workflow to this new version?"
Oh, I see what this person's problem is. He's referring to some lower case "changelog" that everyone calls "release notes".
I agree; the git log is not your release notes.
Please don't call "release notes" "changelog" in 2022.
Release notes aren't a change log because, doh, they don't (exactly) log the changes.
Regarding the conflicts issue, this is where tools like Changie can help: instead of modifying one single file, every merge adds its own separated entry. They are then assembled together at release time with `changie batch $VERSION` to produce a single file for $VERSION, then merged into the global changelog/release notes file with `changie merge`.
If "every merge adds its own separated entry" and that doesn't refer to a special section of the commit message, you're doing something silly.
For these folks, putting deliberate effort into change logs, release notes, and documentation feels wasteful.
My hunch is that this is due to a missing feedback loop: we are unlikely to get feedback about documentation, and more likely to get feedback on our project’s code.
My own writing improved after a past project had a strong feedback loop with my documentation’s intended audience. This has been so damn rare in my career, that it’s never surprising when I meet programmers who are uncomfortable with technical writing.
- they are programmers, automating things is their job, that's what they are good at, so of course they will do that
- there is the general "don't repeat yourself" idea. Documentation repeats the code so, ideally, if both are needed one should be generated from the other. Sometimes, the code can be generated from the documentation, but most of the times you can't, so documentation becomes secondary to the code.
It's worth rewriting the history to achieve this and squashing or splitting commits until this is the case. You shouldn't do this for the benefit of your users or a changelog, you should do this in order that it is easier to bisect the history or for other contributors to understand exactly the change a commit relates to. There is nothing worse than commits which combine a working bug fix with a half-written feature -- split them out!
Obviously, it's possible to inadvertently create a misleading history by re-arranging the order that work was done or getting rid of failed attempts at a solution, but generally the false reality is easier to understand and good understanding is key.
Relnotes: yes, or text for the release notes
I think that squashing and merging, much like commit messages and changelogs, also have different target audiences.
If there are contributors to the project who aren't proficient with git, asking them to rebase would be a huge obstacle for them and create a much worse mess. Squashing simplifies their workflow and allows any mistakes (e.g. checking in the database, accidental merges from the wrong branch, etc.) to be cleaned up and kept out of the permanent history.
I thought I had written about this way back as well, but what I found instead is a post from 2005 that’s tangentially related. I remember that some projects back in the day tried to replicate the equivalent of git log in their ChangeLog file… by hand!
Here is the post: https://jmmv.dev/2005/08/manual-changelogs-thing-of-past.htm... — and pardon the English and its structure. Not as nice as I’d like it to be, but that was written 17 years ago!
On the other hand, it takes a lot of discipline to make the second branch useful at all. If you constantly make short commits with messages like "stuff", why bother keeping them in the repo at all? There's a ton of junk you don't need in the typical code review, and making it useful requires... Discipline.
A git log is not a change log, sure. But PRs can contain a lot of useful information.
Otherwise your PM can write change logs basing off of JIRA or something. Your change log generated from commits can still be useful for incident management, etc.
plus maybe a 'fixes' list (because a spec file doesn't need to say 'what used to not work')
then compute diffs of these using git history to produce a changelog
Or if you didn’t actually release something you thought you did.