Version control: best practices • Hacker News Board

Re: Version control: best practices

#11

Post by Smudge » Thu, Jun 05, 2014, 6:44 PM UTC

VBprogrammer wrote: post #4

> Good, descriptive commit messages All of the examples given in the image going that heading I'd say are mediocre at best. The code changes should tell you what has changed, if I'm looking back through your commit history what I'm usually trying figure out is why you've changed something. A ticket number is often the single most useful thing, ideally followed why a very brief what you've changed and as much informat…

You're right -- the diff answers the what, so being able to answer the why concisely is what makes a good commit message.

Ticket numbers are important context, but unless it is a one-off commit you can instead put that info in the merge commit (as if saying, all of these commits I'm merging were made as part of fixing Issue #17).

Some people like to use squash extensively for that reason, but then you don't have the same granularity when it comes to reverting individual bits of that commit without reverting the entire bugfix. (This assumes that every commit leaves the code in a working state with passing tests).

Re: Version control: best practices

#12

Post by smathieu » Thu, Jun 05, 2014, 6:46 PM UTC

reledi wrote: post #5

Adding to GitHub Pull Requests, I recommend opening them early. This allows reviews to happen early and often, instead of reviewing one giant chunk of changes at the end which may get rejected because it has too many problems. Plan out the tasks in your PR to communicate what still needs to be done -- I like to use GitHub Flavored Markdown task lists. Here's a fish script I use when creating a new branch. It opens a…

Another good thing about this is that if you have CI setup to work with Github, you can also run all of your test suite quickly and asynchronously for each commit.

Re: Version control: best practices

#13

Post by erichurkman » Thu, Jun 05, 2014, 6:46 PM UTC

Smudge wrote: post #11

VBprogrammer wrote: post #4

> Good, descriptive commit messages All of the examples given in the image going that heading I'd say are mediocre at best. The code changes should tell you what has changed, if I'm looking back through your commit history what I'm usually trying figure out is why you've changed something. A ticket number is often the single most useful thing, ideally followed why a very brief what you've changed and as much informat…

You're right -- the diff answers the what , so being able to answer the why concisely is what makes a good commit message. Ticket numbers are important context, but unless it is a one-off commit you can instead put that info in the merge commit (as if saying, all of these commits I'm merging were made as part of fixing Issue #17). Some people like to use squash extensively for that reason, but then you don't have the…

Issue numbers in each commit can also help when you end up cherry-picking commits from one branch to another.

Re: Version control: best practices

#14

Post by VBprogrammer » Thu, Jun 05, 2014, 6:50 PM UTC

erichurkman wrote: post #13

Smudge wrote: post #11

Earlier quoted context omitted.

You're right -- the diff answers the what , so being able to answer the why concisely is what makes a good commit message. Ticket numbers are important context, but unless it is a one-off commit you can instead put that info in the merge commit (as if saying, all of these commits I'm merging were made as part of fixing Issue #17). Some people like to use squash extensively for that reason, but then you don't have the…

Issue numbers in each commit can also help when you end up cherry-picking commits from one branch to another.

Yeah, I prefer the issue number in each commit as it makes the commit log more readable to me. But do a decent job of everything else and that is a very small nit-pick.

Re: Version control: best practices

#15

Post by Smudge » Thu, Jun 05, 2014, 6:50 PM UTC

dmmalam wrote: post #7

Looks very sensible. We tend to not have a long running dev branch, and just cut features branches off master, similar to the 'how github uses github to build github' presentation [1]. Is anyone making squashing part of their workflow? We seem to prefer just plain merges with rebase. [1] http://zachholman.com/talk/how-github-uses-github-to-build-g...

Instead of squashing everything into a single master commit for each bugfix (which I've seen teams do), I use a merge commit to signify a set of commits that comprise a single feature or fix. (`git merge --no-ff`)

I make use of squashing when there is a clear group of commits that all change the same few lines of code or are conceptually part of the same incremental change. But then each incremental change (from working state to newer working state) I leave as a separate commit.

Re: Version control: best practices

#16

Post by Smudge » Thu, Jun 05, 2014, 6:54 PM UTC

erichurkman wrote: post #13

Smudge wrote: post #11

Earlier quoted context omitted.

You're right -- the diff answers the what , so being able to answer the why concisely is what makes a good commit message. Ticket numbers are important context, but unless it is a one-off commit you can instead put that info in the merge commit (as if saying, all of these commits I'm merging were made as part of fixing Issue #17). Some people like to use squash extensively for that reason, but then you don't have the…

Issue numbers in each commit can also help when you end up cherry-picking commits from one branch to another.

I guess in that scenario my preference would be to amend the cherry-picked commit's message to include why it was cherry-picked.

The alternative in your case (leaving it as-is, with an issue number) implies that the entire commit addresses that particular issue number, which may not be true. (It may be part of a series of commits for that issue)

Re: Version control: best practices

#17

Post by tomswartz07 » Thu, Jun 05, 2014, 6:54 PM UTC

VBprogrammer wrote: post #4

> Good, descriptive commit messages All of the examples given in the image going that heading I'd say are mediocre at best. The code changes should tell you what has changed, if I'm looking back through your commit history what I'm usually trying figure out is why you've changed something. A ticket number is often the single most useful thing, ideally followed why a very brief what you've changed and as much informat…

One of my biggest pet peeves is poorly formatted commit messages.

I have one coworker who continually fails to put the empty line between the first line and the body of the commit message. So many of our git logs are littered with 100+ character long messages.

The other commenters hit the nail on the head with the fomatting. Short, precise, and properly formatted.

Re: Version control: best practices

#18

Post by VBprogrammer » Thu, Jun 05, 2014, 6:58 PM UTC

smathieu wrote: post #9

VBprogrammer wrote: post #4

> Good, descriptive commit messages All of the examples given in the image going that heading I'd say are mediocre at best. The code changes should tell you what has changed, if I'm looking back through your commit history what I'm usually trying figure out is why you've changed something. A ticket number is often the single most useful thing, ideally followed why a very brief what you've changed and as much informat…

I think the point was mostly that 'lol' or 'meh' is a completely useless comment. It's true that there's a lot of room for improvements in the given example. Still, they do provide some context to people who actually understand the application they are working on. Does anyone know of good open source project that uses Git messages extremely well that we could use as an example?

Yes, they are clearly vastly superior to 'lol', 'meh' or worse 'fix'. Still, I think my point stands that they could be better.

Re: Version control: best practices

#19

Post by tomswartz07 » Thu, Jun 05, 2014, 6:59 PM UTC

smathieu wrote: post #9

VBprogrammer wrote: post #4

> Good, descriptive commit messages All of the examples given in the image going that heading I'd say are mediocre at best. The code changes should tell you what has changed, if I'm looking back through your commit history what I'm usually trying figure out is why you've changed something. A ticket number is often the single most useful thing, ideally followed why a very brief what you've changed and as much informat…

I think the point was mostly that 'lol' or 'meh' is a completely useless comment. It's true that there's a lot of room for improvements in the given example. Still, they do provide some context to people who actually understand the application they are working on. Does anyone know of good open source project that uses Git messages extremely well that we could use as an example?

Not to toot my own horn, but I have a few minor projects that I try to meticulously document with the git commit messages.

https://github.com/tomswartz07/linux-configs/commit/3684d3ad... is an example of one.

Re: Version control: best practices

#20

Post by babuskov » Thu, Jun 05, 2014, 7:06 PM UTC

VBprogrammer wrote: post #8

VBprogrammer wrote: post #4

> Good, descriptive commit messages All of the examples given in the image going that heading I'd say are mediocre at best. The code changes should tell you what has changed, if I'm looking back through your commit history what I'm usually trying figure out is why you've changed something. A ticket number is often the single most useful thing, ideally followed why a very brief what you've changed and as much informat…

As an example of what I'd like to read: #2313 Change expected value to a float field. django-haystack stores decimal fields as strings internally. This means that when we order by expected value small values (e.g '9e-08') are sorted before larger values.

I prefer to keep such comments in the code, not in the commit message. It is highly unlikely that anyone coming to do some changes to that part of the code would go and read a year-old commit message that he isn't even aware exists.