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

31–40 of 92 posts

Re: Git log is not a changelog

#31

Post by fraudsyndrome »

ArrayBoundCheck wrote: post #29
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"

Doesn't mean others are in the same boat as you. The team I work on frequently write detailed commits to the point where I can (and have several times) successfully searched information from years ago on a block of code with the ticket number and the developers (even myself) reasoning at the time.

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.

Re: Git log is not a changelog

#32

Post by plorkyeran »

RustyRussell wrote: post #17
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…

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.

Setting `CHANGELOG.md merge=union` in .gitattributes mostly eliminates spurious merges conflicts on the changelog.

Re: Git log is not a changelog

#33

Post by plorkyeran »

ArrayBoundCheck wrote: post #29
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"

Never looking at git history is like, not reading comments or something. It's an incredibly valuable resource for understanding why the existing code is the way it is.

Re: Git log is not a changelog

#34

Post by ArrayBoundCheck »

fraudsyndrome wrote: post #31
ArrayBoundCheck wrote: post #29

Earlier quoted context omitted.

> 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"

Doesn't mean others are in the same boat as you. The team I work on frequently write detailed commits to the point where I can (and have several times) successfully searched information from years ago on a block of code with the ticket number and the developers (even myself) reasoning at the time. 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…

Why are you searching a year or more back? Is this using git blame?

Re: Git log is not a changelog

#35

Post by plorkyeran »

Karellen wrote: post #12

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…

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.

Re: Git log is not a changelog

#36

Post by ArrayBoundCheck »

plorkyeran wrote: post #33
ArrayBoundCheck wrote: post #29

Earlier quoted context omitted.

> 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"

Never looking at git history is like, not reading comments or something. It's an incredibly valuable resource for understanding why the existing code is the way it is.

You didn't answer why. My code passes all the unit test and we almost always have real code using it immediately. The function works. Why am I reading it? The only thing I read are bug reports (usually a spec problem, not normally a logic bug) and new features, or test outputs

Re: Git log is not a changelog

#37

Post by kazinator »

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.

Re: Git log is not a changelog

#38

Post by shakna »

ArrayBoundCheck wrote: post #34
fraudsyndrome wrote: post #31

Earlier quoted context omitted.

Doesn't mean others are in the same boat as you. The team I work on frequently write detailed commits to the point where I can (and have several times) successfully searched information from years ago on a block of code with the ticket number and the developers (even myself) reasoning at the time. 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…

Why are you searching a year or more back? Is this using git blame?

To explain why a certain block of code exists. When the code came into existence is rarely that important. You just want to know why.

Why does the code fence against a particular circumstance you didn't think should be possible? Why does it call out to something you think is unrelated? Those questions can be answered by a proper commit message.

Re: Git log is not a changelog

#39

Post by ArrayBoundCheck »

shakna wrote: post #38
ArrayBoundCheck wrote: post #34

Earlier quoted context omitted.

Why are you searching a year or more back? Is this using git blame?

To explain why a certain block of code exists. When the code came into existence is rarely that important. You just want to know why. Why does the code fence against a particular circumstance you didn't think should be possible? Why does it call out to something you think is unrelated? Those questions can be answered by a proper commit message.

I set a breakpoint and run the test suite for that answer

Re: Git log is not a changelog

#40

Post by Larrikin »

ArrayBoundCheck wrote: post #29
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"

I think you just haven't discovered you can? I don't know of anyone arbitrarily looking through logs, but it's incredibly useful with git blame when you get to a section of code and don't understand it or typically it's done in an odd or unintuitive way. The blame shows who wrote it, information as to what they were working on via the actual commit message, and branch information.

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.

Post reply on HN