5 ms·

Not to sound like I'm boasting, but most of my commits are far too atomic to warrant more than a first line. If I need to write several paragraphs about the cha

Not to sound like I'm boasting, but most of my commits are far too atomic to warrant more than a first line. If I need to write several paragraphs about the changes I'm making, it's definitely too large a commit.

MostAwesomeDude 15y ago
So, you've never had a commit like this one? deep/magic: Commit changes even if not dirty. Changesets are somewhat magical these days (obviously!); even if they are not dirtied; they could end up being really, *really* bogus as far as their on-disk status. The reason, as far as I can tell, is that in deep/wizardry, we are being very liberal about our modifications to the on-disk data structures without actually considering whether or not any other owner of that structure is pending changes to commit. As a result, we could end up heavily corrupting these structures if we're not careful. I'm not altering the comments in the file because, frankly, the comments imply that we should have already been doing this. I just changed the code to match. Fixes #4242. Finally! Time to go grab a beer. :3 Tests: +5 working mad/deep/magic.py | 1 + 1 file changed, 1 insertion(+), 0 deletions(-)
- prodigal_erik 15y ago
  I would prefer to see that rationale in the comments or some implementation doc or something. In the git history it's eventually going to be troublesome to unearth, unless the change remains intact enough for "git blame" to give you a pointer to that old commit, or your whole team standardizes keywords for more searchable commit messages. And if your team does have a way to find that explanation, you then need some way for them to discover whether it has become inaccurate over time.
  - MostAwesomeDude 15y ago
    You are implying that "the team" actually reads that section of the code, and furthermore that they will actually attempt to fix any issues found in that section rather than just go find the original author and ply him with beer to get him to fix it.
  - rmccue 15y ago
    Comments about the change itself, and the rationale behind it, should go in commit messages. Comments about the implementation itself should go in the code. Granted, there is some overlap between the two, in which case, go with code only (since it's part of the commit anyway).
billpatrianakos 15y ago
No one is saying to write a lot. The point is to write enough. You should basically be able to hand someone the commit log and they should be able to easily figure out how the current state of the code came into being without having to dig into the code. Small commits are fine and often don't warrant several lines. I've done that too. It's often a fine line between a commit that's too big and too small. At the same time, just because a commit warrants a few sentences about it that doesn't necessarily mean it was too large. I don't want to keep being long winded here so I won't go into examples as I think we've all seen situations like what I'm talking about but I'd be happy to add an example later if necessary.
dustingetz 15y ago
> If I need to write several paragraphs about > the changes I'm making, it's definitely too > large a commit. careful, this is subjective, and a lot of people consider it best practice to commit in small chunks but rewrite local history right before we push to squash everything into one changeset for the issue. the idea being it keeps the master history high level which is more useful when looking at other-peoples-commits.

MostAwesomeDude 15y ago

So, you've never had a commit like this one? deep/magic: Commit changes even if not dirty. Changesets are somewhat magical these days (obviously!); even if they are not dirtied; they could end up being really, *really* bogus as far as their on-disk status. The reason, as far as I can tell, is that in deep/wizardry, we are being very liberal about our modifications to the on-disk data structures without actually considering whether or not any other owner of that structure is pending changes to commit. As a result, we could end up heavily corrupting these structures if we're not careful. I'm not altering the comments in the file because, frankly, the comments imply that we should have already been doing this. I just changed the code to match. Fixes #4242. Finally! Time to go grab a beer. :3 Tests: +5 working mad/deep/magic.py | 1 + 1 file changed, 1 insertion(+), 0 deletions(-)

prodigal_erik 15y ago
I would prefer to see that rationale in the comments or some implementation doc or something. In the git history it's eventually going to be troublesome to unearth, unless the change remains intact enough for "git blame" to give you a pointer to that old commit, or your whole team standardizes keywords for more searchable commit messages. And if your team does have a way to find that explanation, you then need some way for them to discover whether it has become inaccurate over time.
- MostAwesomeDude 15y ago
  You are implying that "the team" actually reads that section of the code, and furthermore that they will actually attempt to fix any issues found in that section rather than just go find the original author and ply him with beer to get him to fix it.
- rmccue 15y ago
  Comments about the change itself, and the rationale behind it, should go in commit messages. Comments about the implementation itself should go in the code. Granted, there is some overlap between the two, in which case, go with code only (since it's part of the commit anyway).

billpatrianakos 15y ago

No one is saying to write a lot. The point is to write enough. You should basically be able to hand someone the commit log and they should be able to easily figure out how the current state of the code came into being without having to dig into the code. Small commits are fine and often don't warrant several lines. I've done that too. It's often a fine line between a commit that's too big and too small. At the same time, just because a commit warrants a few sentences about it that doesn't necessarily mean it was too large. I don't want to keep being long winded here so I won't go into examples as I think we've all seen situations like what I'm talking about but I'd be happy to add an example later if necessary.

dustingetz 15y ago

> If I need to write several paragraphs about > the changes I'm making, it's definitely too > large a commit. careful, this is subjective, and a lot of people consider it best practice to commit in small chunks but rewrite local history right before we push to squash everything into one changeset for the issue. the idea being it keeps the master history high level which is more useful when looking at other-peoples-commits.