8 ms·

Git log is not a changelog

124 points by agateau 4y ago

mulle_nat 4y ago
I use the git log to feed my changelog. I prefix the stuff that's supposed to go in the release notes with a asterix and the technical boring stuff is just a normal line. Then at release time I have a script that pulls the asterix prefixed lines from the change log into the RELEASENOTES.md. I wouldn't want to bother with more.
- kreeben 4y ago
  How do you know that your asterixed commit should go into the release notes? What if... * 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.
  - ehPReth 4y ago
    you just wouldn't put a * in front of the second one
    - justinfrankel 4y ago
      or you might have an alternate prefix for "things that go in development build changelogs but not final changelogs", e.g. "-"
- slavik81 4y ago
  When you squash and merge a PR, GitHub will by default prefix commit messages of the squashed commits with an astrix.
sss111 4y ago
use https://www.conventionalcommits.org/en/v1.0.0/ https://www.conventionalcommits.org/en/v1.0.0/, it has extensions that can autogenerate a nice looking changelog.
- jasonpeacock 4y ago
  Yep, something like Git Cliff[1] is great for generating release notes from your commit messages. 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. [1] https://github.com/orhun/git-cliff https://github.com/orhun/git-cliff
- difosfor 4y ago
  Yeah, at work we combine that with https://semantic-release.gitbook.io/semantic-release/ https://semantic-release.gitbook.io/semantic-release/ for changelog generation and continuous deployment to NPM. It takes some getting used to, but I like it.
- agateau 4y ago
  This is the kind of tools I dislike. It does generate a "nice looking changelog", but the result is not as useful as a separately written changelog, because the content is not curated, so the signal-noise ratio can be quite high.
foxhop 4y ago
no changelog until somebody complains?
_ph_ 4y ago
Yes, a commit log isn't a changelog. However, a good commit log can make writing your change log much easier. While this isn't an automatic process, writing a changelog becomes a bit of filtering of the commit messages as well as rephrasing them for the intended audience.
cperciva 4y ago
FreeBSD uses Relnotes: yes, or text for the release notes in commit messages to note that the commit has significant user-visible effects.
lhnz 4y ago
I think commits should contain atomic-yet-meaningful changes and the commit message should describe this as well as possible. 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.
- hk1337 4y ago
  Yeah, we don’t do much but I started writing up a brief description with a link to the PR, hotfix, or commit, so we can easily find links to relevant changes if we need to. It’s not that difficult to write it up manually. Automating it is too prone to either errors or a less than helpful message.
GauntletWizard 4y ago
The missing part of this is filtering git history with "git log --first-parent", but that only works if your repo has good a) merge commit messages and b) hygiene in creating your merges so that your "Pretty" history is on branch 1. 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.
Karellen 4y ago
That depends what you mean by a changelog. 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-Logs https://www.gnu.org/prep/standards/standards.html#Change-Log... [1] https://www.gnu.org/prep/standards/standards.html#NEWS-File https://www.gnu.org/prep/standards/standards.html#NEWS-File
- plorkyeran 4y ago
  GNU's notion of a changelog predates the widespread use of source control, and is indeed there to cover which is now covered by git history. It's not what anyone using modern software development approaches means by a changelog.
  - Karellen 4y ago
    > It's not what anyone using modern software development approaches means by a changelog. 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
- agateau 4y ago
  I agree, I used to have a NEWS file in my projects (later a NEWS.md), but as others commented, the signification of the term "changelog" has changed. Sites like https://keepachangelog.com/ https://keepachangelog.com/ really refers to release notes or news.
teeray 4y ago
The purpose of a git commit message is to answer the question “why does this commit exist?” That is the principal question you should be answering when you type `git commit`. This is the question you will be asking yourself when you find that commit in `git blame` or if it shows up in `git bisect`. Try to help your future self out. 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.
- RustyRussell 4y ago
  We autogenerate our CHANGELOG.md extract from Changelog-[section] our git commit messages (Release Captain massages them if necessary), and have a GH bot which checks that you have a Changelog- note somewhere in your PR commits (can be Changelog-None: ....). This avoid merge hell on the CHANGELOG.md file.
  - Ologn 4y ago
    > 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...
  - plorkyeran 4y ago
    Setting `CHANGELOG.md merge=union` in .gitattributes mostly eliminates spurious merges conflicts on the changelog.
    - jmmv 4y ago
      Oh wow, thanks for the tip! Had no idea this existed.
      - 4y ago
taveras 4y ago
I find that many programmers are hyper-focused on writing automation for things that feel like a chore. This thinking has its purpose, but it’s almost an addiction. 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.
- agateau 4y ago
  I very much agree with this. Sometimes it's good to stop and think about what is lost when automating a task instead of doing it manually.
- GuB-42 4y ago
  I think the reason programmers want to automate documentation is: - 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.
mikewhy 4y ago
At work we squash and use standard-version to create a generic change log, then have a script that ingests that change log and goes to the PR to grab any associated tickets, screenshots, and release notes the developer may have written. The body of the PR is split into sections (just using markdown headers), so there is control over what goes into the release notes. A git log is not a change log, sure. But PRs can contain a lot of useful information.
quickthrower2 4y ago
git log let’s you check if you might be missing something from the change log (aka release notes) though. Or if you didn’t actually release something you thought you did.
yellowapple 4y ago
Alternately: be religious about (merged) branches and changelog entries being 1:1.
bloopernova 4y ago
Use multiple "-m" parameters in your git commit. git commit -m "feat: script pretty print" -m "added variables for bold, normal, and a nice blue arrow" becomes: feat: script pretty print added variables for bold, normal, and a nice blue arrow In your git log output. Use extra "-m" sections for stuff like ticket references, or other relevant information like a link to a design document.
- zach_garwood 4y ago
  MVP
- discodachshund 4y ago
  Alternatively just avoid the `-m` flag and open the message in `$EDITOR`
  - rubyist5eva 4y ago
    But then I have to figure out how to exit vim.
bstar77 4y ago
For me, it's as simple as my audiences are different, hence what I choose to put in them will often be different.
awinter-py 4y ago
instead of a changelog, would be neat to ship a 'spec' file that says what features the codebase provides, as well as detailed semantics 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
kazinator 4y ago
Yes the Git log is the ChangeLog. 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.
- agateau 4y ago
  (Author here) Yes, "release notes" is probably the appropriate term. The issue remains however: many projects generate their release notes from their git commit messages. 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`.
  - kazinator 4y ago
    This is something you could do with a commit hook which verifies that commit messages have a well-formed release notes entry section, and some seven line Awk script to combine them together when needed. 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.
jmmv 4y ago
Agree with the premise of the article: changelogs—or rather, news files—are not the commit history. Describing the changes between releases at a high level is super important but also a skill that’s hard to acquire. 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.html 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!
sudo_chmod777 4y ago
If you write dev facing projects, unless your volume is that high, your commit history can absolutely be your change log using conventional commits. 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.
rurban 4y ago
Apparently nobody knows the difference between NEWS and CHANGELOG anymore. Maybe re-read the GNU coding Standards. https://www.gnu.org/prep/standards/standards.html#NEWS-File https://www.gnu.org/prep/standards/standards.html#NEWS-File
ptx 4y ago
> Git commit messages and changelogs do not have the same target audience. [...] Some people dislike merge commits. [...] If that bothers you, you can always ask contributors to rebase before merging. 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.
Lapsa 4y ago
export that cr*p out of whatever issue tracker you using. and merge commits are great
thiht 4y ago
I completely agree with this. Every single project with « conventional commits » that try to generate release notes end up with completely useless release notes. Just bite the bullet and write for humans, it’s not that hard, especially if you do it on the fly as suggested by the post.
SuperSandro2000 4y ago
NixOS maintainer here and this is really annoying me since months. I can't really know what from a 100+ line git log is a breaking change and needs special attention and what is totally uninteresting for consumers of the piece of software.
dataangel 4y ago
Most software is written for internal use and not sold to external customers. For this case Changelogs are busy work without much utility up until the point your organization is big enough that you and your "customer" may as well be separate companies. In that case you're better off writing a blog post or release announcement than a text file change log which is for grey beards, not users.
wagoodman 4y ago
we use https://github.com/anchore/chronicle https://github.com/anchore/chronicle to generate release notes in a changelog format using the issues and PRs from GitHub as the source of truth. In this way time well spent in the curation of issues and PRs (which is something we need to do anyway) means that we automatically get release notes for free. (disclaimer: I'm the author of chronicle)
lamontcg 4y ago
Your changelog is also not release notes.

124 points by agateau 4y ago

I use the git log to feed my changelog. I prefix the stuff that's supposed to go in the release notes with a asterix and the technical boring stuff is just a normal line. Then at release time I have a script that pulls the asterix prefixed lines from the change log into the RELEASENOTES.md. I wouldn't want to bother with more.

kreeben 4y ago
How do you know that your asterixed commit should go into the release notes? What if... * 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.
- ehPReth 4y ago
  you just wouldn't put a * in front of the second one
  - justinfrankel 4y ago
    or you might have an alternate prefix for "things that go in development build changelogs but not final changelogs", e.g. "-"
slavik81 4y ago
When you squash and merge a PR, GitHub will by default prefix commit messages of the squashed commits with an astrix.

sss111 4y ago

use https://www.conventionalcommits.org/en/v1.0.0/ https://www.conventionalcommits.org/en/v1.0.0/, it has extensions that can autogenerate a nice looking changelog.

jasonpeacock 4y ago
Yep, something like Git Cliff[1] is great for generating release notes from your commit messages. 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. [1] https://github.com/orhun/git-cliff https://github.com/orhun/git-cliff
difosfor 4y ago
Yeah, at work we combine that with https://semantic-release.gitbook.io/semantic-release/ https://semantic-release.gitbook.io/semantic-release/ for changelog generation and continuous deployment to NPM. It takes some getting used to, but I like it.
agateau 4y ago
This is the kind of tools I dislike. It does generate a "nice looking changelog", but the result is not as useful as a separately written changelog, because the content is not curated, so the signal-noise ratio can be quite high.

foxhop 4y ago

no changelog until somebody complains?

_ph_ 4y ago

Yes, a commit log isn't a changelog. However, a good commit log can make writing your change log much easier. While this isn't an automatic process, writing a changelog becomes a bit of filtering of the commit messages as well as rephrasing them for the intended audience.

cperciva 4y ago

FreeBSD uses Relnotes: yes, or text for the release notes in commit messages to note that the commit has significant user-visible effects.

lhnz 4y ago

I think commits should contain atomic-yet-meaningful changes and the commit message should describe this as well as possible. 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.

hk1337 4y ago
Yeah, we don’t do much but I started writing up a brief description with a link to the PR, hotfix, or commit, so we can easily find links to relevant changes if we need to. It’s not that difficult to write it up manually. Automating it is too prone to either errors or a less than helpful message.

GauntletWizard 4y ago

The missing part of this is filtering git history with "git log --first-parent", but that only works if your repo has good a) merge commit messages and b) hygiene in creating your merges so that your "Pretty" history is on branch 1. 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.

Karellen 4y ago

That depends what you mean by a changelog. 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-Logs https://www.gnu.org/prep/standards/standards.html#Change-Log... [1] https://www.gnu.org/prep/standards/standards.html#NEWS-File https://www.gnu.org/prep/standards/standards.html#NEWS-File

plorkyeran 4y ago
GNU's notion of a changelog predates the widespread use of source control, and is indeed there to cover which is now covered by git history. It's not what anyone using modern software development approaches means by a changelog.
- Karellen 4y ago
  > It's not what anyone using modern software development approaches means by a changelog. 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
agateau 4y ago
I agree, I used to have a NEWS file in my projects (later a NEWS.md), but as others commented, the signification of the term "changelog" has changed. Sites like https://keepachangelog.com/ https://keepachangelog.com/ really refers to release notes or news.

teeray 4y ago

The purpose of a git commit message is to answer the question “why does this commit exist?” That is the principal question you should be answering when you type `git commit`. This is the question you will be asking yourself when you find that commit in `git blame` or if it shows up in `git bisect`. Try to help your future self out. 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.

RustyRussell 4y ago
We autogenerate our CHANGELOG.md extract from Changelog-[section] our git commit messages (Release Captain massages them if necessary), and have a GH bot which checks that you have a Changelog- note somewhere in your PR commits (can be Changelog-None: ....). This avoid merge hell on the CHANGELOG.md file.
- Ologn 4y ago
  > 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...
- plorkyeran 4y ago
  Setting `CHANGELOG.md merge=union` in .gitattributes mostly eliminates spurious merges conflicts on the changelog.
  - jmmv 4y ago
    Oh wow, thanks for the tip! Had no idea this existed.
    - 4y ago

taveras 4y ago

I find that many programmers are hyper-focused on writing automation for things that feel like a chore. This thinking has its purpose, but it’s almost an addiction. 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.

agateau 4y ago
I very much agree with this. Sometimes it's good to stop and think about what is lost when automating a task instead of doing it manually.
GuB-42 4y ago
I think the reason programmers want to automate documentation is: - 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.

mikewhy 4y ago

At work we squash and use standard-version to create a generic change log, then have a script that ingests that change log and goes to the PR to grab any associated tickets, screenshots, and release notes the developer may have written. The body of the PR is split into sections (just using markdown headers), so there is control over what goes into the release notes. A git log is not a change log, sure. But PRs can contain a lot of useful information.

quickthrower2 4y ago

git log let’s you check if you might be missing something from the change log (aka release notes) though. Or if you didn’t actually release something you thought you did.

yellowapple 4y ago

Alternately: be religious about (merged) branches and changelog entries being 1:1.

bloopernova 4y ago

Use multiple "-m" parameters in your git commit. git commit -m "feat: script pretty print" -m "added variables for bold, normal, and a nice blue arrow" becomes: feat: script pretty print added variables for bold, normal, and a nice blue arrow In your git log output. Use extra "-m" sections for stuff like ticket references, or other relevant information like a link to a design document.

zach_garwood 4y ago
MVP
discodachshund 4y ago
Alternatively just avoid the `-m` flag and open the message in `$EDITOR`
- rubyist5eva 4y ago
  But then I have to figure out how to exit vim.

bstar77 4y ago

For me, it's as simple as my audiences are different, hence what I choose to put in them will often be different.

awinter-py 4y ago

instead of a changelog, would be neat to ship a 'spec' file that says what features the codebase provides, as well as detailed semantics 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

kazinator 4y ago

Yes the Git log is the ChangeLog. 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.

agateau 4y ago
(Author here) Yes, "release notes" is probably the appropriate term. The issue remains however: many projects generate their release notes from their git commit messages. 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`.
- kazinator 4y ago
  This is something you could do with a commit hook which verifies that commit messages have a well-formed release notes entry section, and some seven line Awk script to combine them together when needed. 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.

jmmv 4y ago

Agree with the premise of the article: changelogs—or rather, news files—are not the commit history. Describing the changes between releases at a high level is super important but also a skill that’s hard to acquire. 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.html 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!

sudo_chmod777 4y ago

If you write dev facing projects, unless your volume is that high, your commit history can absolutely be your change log using conventional commits. 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.

rurban 4y ago

Apparently nobody knows the difference between NEWS and CHANGELOG anymore. Maybe re-read the GNU coding Standards. https://www.gnu.org/prep/standards/standards.html#NEWS-File https://www.gnu.org/prep/standards/standards.html#NEWS-File

ptx 4y ago

> Git commit messages and changelogs do not have the same target audience. [...] Some people dislike merge commits. [...] If that bothers you, you can always ask contributors to rebase before merging. 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.

Lapsa 4y ago

export that cr*p out of whatever issue tracker you using. and merge commits are great

thiht 4y ago

I completely agree with this. Every single project with « conventional commits » that try to generate release notes end up with completely useless release notes. Just bite the bullet and write for humans, it’s not that hard, especially if you do it on the fly as suggested by the post.

SuperSandro2000 4y ago

NixOS maintainer here and this is really annoying me since months. I can't really know what from a 100+ line git log is a breaking change and needs special attention and what is totally uninteresting for consumers of the piece of software.

dataangel 4y ago

Most software is written for internal use and not sold to external customers. For this case Changelogs are busy work without much utility up until the point your organization is big enough that you and your "customer" may as well be separate companies. In that case you're better off writing a blog post or release announcement than a text file change log which is for grey beards, not users.

wagoodman 4y ago

we use https://github.com/anchore/chronicle https://github.com/anchore/chronicle to generate release notes in a changelog format using the issues and PRs from GitHub as the source of truth. In this way time well spent in the curation of issues and PRs (which is something we need to do anyway) means that we automatically get release notes for free. (disclaimer: I'm the author of chronicle)

lamontcg 4y ago

Your changelog is also not release notes.