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

51–60 of 92 posts

Re: Git log is not a changelog

#51

Post by erik_seaberg »

ArrayBoundCheck wrote: post #36
plorkyeran wrote: post #33

Earlier quoted context omitted.

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

If someone complains that our system did something weird, sometimes it’s a mistake we can just fix, but sometimes it’s a non-obvious consequence of some requirement (which I might not have been aware of) that we have to explain to our consumer. It also helps a lot to tell whether it has been like that for a week or five years.

I can’t even imaging having a spec that fully answers anything like this; Microsoft tried for that level of detail but I found they couldn’t keep it up to date.

Re: Git log is not a changelog

#52

Post by Macha »

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 work on several legacy codebases which were:

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

Re: Git log is not a changelog

#53

Post by tsimionescu »

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"

If you have never needed to find out why a particular piece of code is the way it is, then you have been very lucky to work in very clean code bases. In my own experience, this has been an infrequent but inevitable part of work - maybe once a month or so, I have had to understand whether a particular piece of code, that seems wrong, had a good reason for existing or not.

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.

Re: Git log is not a changelog

#54

Post by d3nj4l »

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.

Why don’t you put that as a comment on the code?

Re: Git log is not a changelog

#55

Post by ptx »

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

Re: Git log is not a changelog

#56

Post by lexicality »

d3nj4l wrote: post #54
shakna wrote: post #38

Earlier quoted context omitted.

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.

Why don’t you put that as a comment on the code?

Comments are for why code is written the way it is, commits are for why the code is written in the first place.

You _could_ tag every line of code with

  // JIRA-123 The PM wants this to be blue
but if you did it would become unreadable and wouldn't be kept up to date.

Re: Git log is not a changelog

#58

Post by agateau »

taveras wrote: post #15

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…

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.

Re: Git log is not a changelog

#59

Post by agateau »

kazinator wrote: post #37

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…

(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`.

Re: Git log is not a changelog

#60

Post by agateau »

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…

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/ really refers to release notes or news.
Post reply on HN