Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Git log is not a changelog

agateau.com

Post reply on HN
Print view View original

21–30 of 92 posts

Re: Git log is not a changelog

#21

Post by icedchai »

teeray wrote: post #14

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 abo…

A couple jobs ago, I was at a company that had a "mandatory" squash / rebase / merge workflow so history would be clean. On top of that, they forced all their developers to update a change log as part of the merge. That file was a source of contention / merge conflict for nearly every PR, often requiring additional rounds of rebasing. On top of that, it was full of information that could've been gathered from the git log. Big waste of time, in my opinion.

Re: Git log is not a changelog

#22

Post by ChadNauseam »

icedchai wrote: post #21
teeray wrote: post #14

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 abo…

A couple jobs ago, I was at a company that had a "mandatory" squash / rebase / merge workflow so history would be clean. On top of that, they forced all their developers to update a change log as part of the merge. That file was a source of contention / merge conflict for nearly every PR, often requiring additional rounds of rebasing. On top of that, it was full of information that could've been gathered from the git…

We had something kind of similar, but designed to avoid merge contention. We had each PR include a randomly-generated number, and a `changelogs/` folder where you could add a `${number}.md` that was either blank or had a message that would be added to the changelog. After you made the PR, you could run a bash script to edit the PR to contain the number and generate the `${number}.md` file.

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.

Re: Git log is not a changelog

#23

Post by slavik81 »

mulle_nat wrote: post #2

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.

When you squash and merge a PR, GitHub will by default prefix commit messages of the squashed commits with an astrix.

Re: Git log is not a changelog

#24

Post by bloopernova »

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.

Re: Git log is not a changelog

#25

Post by hk1337 »

lhnz wrote: post #9

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 th…

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.

Re: Git log is not a changelog

#27

Post by awinter-py »

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

Re: Git log is not a changelog

#28

Post by justinfrankel »

ehPReth wrote: post #10
kreeben wrote: post #7

Earlier quoted context omitted.

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.

you just wouldn't put a * in front of the second one

or you might have an alternate prefix for "things that go in development build changelogs but not final changelogs", e.g. "-"

Re: Git log is not a changelog

#29

Post by ArrayBoundCheck »

teeray wrote: post #14

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 abo…

> The purpose of a git commit message is to answer the question “why does this commit exist?”

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"

Re: Git log is not a changelog

#30

Post by zach_garwood »

bloopernova wrote: post #24

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.

MVP
Post reply on HN