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

Rob Pike on good commit messages (2014)

groups.google.com

Post reply on HN
Print view View original

51–60 of 98 posts

Re: Rob Pike on good commit messages (2014)

#51

Post by katbyte »

dtech wrote: post #14
amelius wrote: post #8

Earlier quoted context omitted.

Ok, but how much time have you "wasted" wondering what a piece of code was doing versus how much time would you have wasted writing good commit messages?

It's a balance, but I've definitely seen that a good commit title can massively help newcomers, yourself when you can't remember why something is the way it is and can be a boon when debugging. A nice balance I've found is to not care while developing, but then squash all commits into a single one when merging a pull request and give that a good message.

This is what I do, means I don’t have to worry about describing a “fix linting errors” commit. Just on squash merge ensure the commit message captures what’s required (and on gh the pr is automatically included and I typically put any linked issues in the additional info area)

Re: Rob Pike on good commit messages (2014)

#52

Post by RussianCow »

SkyPuncher wrote: post #44

Personally, I find little use to stashing a lot into a commit message. Nearly all work is managed outside of Git. Provide a short description, reference the work you're doing (a ticket, a PR, etc), and hold the discussion there. Rebase many, meaningless commits into a single one for integration purposes.

I used to believe this as well, but then a company I worked for switched away from GitHub (we used GitHub Issues prior), and we lost all of that information. Commit messages are immutable, whereas anything else can easily disappear or become inaccessible.

Re: Rob Pike on good commit messages (2014)

#53

Post by weberc2 »

deanmoriarty wrote: post #4

After being in the field for almost a decade now and guilty of so many poor commit messages, I came to the firm realization that a very important trait of a good software engineer is the ability and diligence to write detailed commit messages, and I would have never remotely imagined this during the first few years of my career (I was "raised" in companies who didn't care at all about this and all commits were always…

We tag each commit with the (JIRA) ticket ID. The ticket has the broader business context, and the commit message is generally shorter. There's still some gap between the one-line commit message and the ticket ID, but it hasn't really caused problems in our org to my knowledge.

Re: Rob Pike on good commit messages (2014)

#55

Post by pavon »

Pxtl wrote: post #39

We take a "PR all the things" approach using MS VSTS/DevOps. Every PR needs a work-item attached and a description, and those get cooked into the commit. We always squash, but squashing is dubious - if the any of the commits of the branch are still kicking around in other branches, it looks like they're ahead when they're not. Imho, this is a huge flaw in GIT - I don't want to squash, but I do want a clean history an…

> VSTS logs the PR number and the relevant work-items in the message so for any given commit it's easy to get back to the PR where you can see the detailed discussion of the change, requirements, etc.

I've worked on a couple project that took the approach of documenting the details of what was done in the bug tracker (or PR/MR), etc, and then just putting the bug# and a one-line description in the commit history.

In every one of these projects, we ended up later moving to a different bug tracking system. In some cases the bugs were transferred, but the numbers were not, in others nothing was transferred. Suddenly all those bug numbers in the commit history were completely meaningless and useless.

I'm now a strong advocate that the detailed documentation should be in the commits messages themselves. One of my biggest complaints with gitlab is that you spend all this time writing a good MR description, and then it has no mechanism for including that description in the actual merge commit.

Re: Rob Pike on good commit messages (2014)

#56

Post by alunchbox »

deanmoriarty wrote: post #4

After being in the field for almost a decade now and guilty of so many poor commit messages, I came to the firm realization that a very important trait of a good software engineer is the ability and diligence to write detailed commit messages, and I would have never remotely imagined this during the first few years of my career (I was "raised" in companies who didn't care at all about this and all commits were always…

Assuming you're doing Git based flow branching off of Develop or Master to do changes. Before merging your changes back in do you rebase and cleanup the messages or squash? I feel like every company I work for just does merges everywhere and history is 99% unreadable at this point without filtering out certain things on the log and even then.

Any tips on how you're able to keep things clean for the entire team ? What's your usual workflow? I've read through Martin Flower and a few other blogs on this topic yet have never understood how to avoid "add x", "fix foo".

Re: Rob Pike on good commit messages (2014)

#57

Post by pavon »

iudqnolq wrote: post #49
jgalt212 wrote: post #40

Earlier quoted context omitted.

this makes perfect sense and one should show care when constructing commit messages. That being said, if commit messages require too much care, then folks will start to make less commits as they become rather expensive to do. As with all things in life, when and how often to commit is a balance.

What do you think about committing with one-liners as you develop so that you can rollback, and then completely rewriting history before pushing?

I absolutely agree that you should commit early and often, and that short one-liners for those commits are fine. It is when you go to merge that you need to have good messages and there are several ways you can do that, depending on your team's preferences:

* You can rebase and groom your commits into meaningful sets of changes each with good descriptions (how Linux uses git).

* You can squash all the commits, and always just have a single commit for each merge with a detailed description.

* You can keep your full commit history as a record of how the work was actually done (Fossil encourages this philosophy), but always have a detailed merge commit that can stand-alone in describing all the work done in that merge.

Re: Rob Pike on good commit messages (2014)

#58

Post by saagarjha »

ses1984 wrote: post #30
deanmoriarty wrote: post #9

Earlier quoted context omitted.

It has been an obvious net time gain for my projects. I do a lot of system programming, and often there are very complex reasons why a particular function is called in a non-obvious way, especially after tricky bugfixes. Having a somewhat detailed written record associated with the commit, that won't rot like an inline code comment would, has been very useful in my experience. And all my thoughts become instantly ava…

>that won't rot like an inline code comment would It's a balance between rot and visibility, right? Unless you code with commit messages always visible, you have to go out of your way to look at them. If the interesting line changes even a little bit, you could hide the commit message explaining everything with one that explains a small change. If I could only have one, I would rather have comments visible in the cod…

> Unless you code with commit messages always visible

I do this when tracking down bugs or trying to figure out the design of a particular component.

Re: Rob Pike on good commit messages (2014)

#59

Post by saagarjha »

RussianCow wrote: post #50
hprotagonist wrote: post #3

At about the same time, Chris Beams wrote this, which I have loved ever since: https://chris.beams.io/posts/git-commit/ I note with some glee that magit colorizes my commit text and flags long lines,etc. largely in the style of this advice. The money: The seven rules of a great Git commit message Keep in mind: This has all been said before. Separate subject from body with a blank line Limit the subject line to 50 cha…

> Limit the subject line to 50 characters It's nearly impossible to get certain points across in 50 characters. I keep mine under 72, and even then, I sometimes struggle to adequately describe a change in that little space, even at a high level, to the point that it would be useful for someone searching for something. Honestly, all of this stuff matters way less than the actual content of the commit message anyway. S…

> It's nearly impossible to get certain points across in 50 characters.

Usually that kind of stuff goes in the body of the commit message.

Post reply on HN