4 ms·

Then don't write commit messages for the future, write them for reviewers. Seriously, as somebody who reviews a lot of code, well-written commit messages are a

Then don't write commit messages for the future, write them for reviewers. Seriously, as somebody who reviews a lot of code, well-written commit messages are a godsend. It's an awful shame that GitHub doesn't allow commenting on commit messages. It's as if GitHub is being run by people who just don't know how Git is meant to be used.

u801e 3y ago
> It's an awful shame that GitHub doesn't allow commenting on commit messages. You actually can comment on a commit itself. I'm in the habit on middle-clicking on the sha1 link of commits in a PR and looking at the commit itself. You can comment on lines in the commit, and there's a text area at the bottom where you can comment on the entire commit itself. I'll then follow up with making a comment on the PR linking the commit (pasting the sha1 link) and saying I made a few comments here. > It's as if GitHub is being run by people who just don't know how Git is meant to be used. Github wasn't really designed with code review in mind. A lot of the features they added over the years for review appear to be hacked on rather than fixing fundamental design issues (like being able to comment on commit messages without having to jump through a bunch of hoops). Review systems like gerrit, phabricator, review board, or even email, do a much better job at exposing individual commits and their associated metadata like the commit message.
- sverhagen 3y ago
  I don't think they were suggesting to review the individual commits, rather the (individual) commit messages. Commit messages are text, so you could have a similar line by line click-and-comment review interface as you already have for the code changes.
  - u801e 3y ago
    > I don't think they were suggesting to review the individual commits, rather the (individual) commit messages. That's a good point. > Commit messages are text, so you could have a similar line by line click-and-comment review interface as you already have for the code changes. It would be nice if something like that was available in Github. The closest thing you could do would be to copy the commit title and body and paste it as quoted text in the text area and then comment on it inline.
erhaetherth 3y ago
I write commit messages for future-me. Sooner or later I'm going to encounter the same problem again and wonder how I solved it last time. If I have a vague inkling that I dealt with this before, all I have to do is searching through my commit history and I can find it again. I can search my author (me), I can search by date, I can search by what files I touched. It's lovely.
michaelcampbell 3y ago
> Seriously, as somebody who reviews a lot of code, well-written commit messages are a godsend. This is the issue; are commits in your codebase for the reviewers? Or for FutureDev to see what the hell happened? These are often very different things, and most process models favor one of these at the total expense of the other.
- atq2119 3y ago
  Interesting that you perceive a dichotomy there, can you elaborate where you see the conflict? As a reviewer, I see myself as a (extremely near, time T+epsilon) future developer who is trying to see what the hell is happening.
  - michaelcampbell 3y ago
    There's a dichotomy between a history of actual code changes, oopsies and redos included, and "a carefully crafted story of the intent of this change". One is an ugly reality, the other is a pretty story of intention. The process vs. the final result. Both are useful, but in different contexts. The latter is good for a PR, but when optimized for that often loses a lot of other context, and is meant to be a throwaway bit of data that once the PR is approved, never seen again, nor meant to be seen again. The former can delve a bit into what experiments were tried and abandoned and can give a lot more meaning to the final result. > As a reviewer, I see myself as a (extremely near, time T+epsilon) future developer who is trying to see what the hell is happening I generally find this to not be the case; reviewing is to see what this might "break" and has IME been extremely transactional. Not all PRs nor reviewers are like this of course, and you may not be one. But, again, IME, this is the "modern" workflow.
    - Capricorn2481 3y ago
      > The former can delve a bit into what experiments were tried and abandoned and can give a lot more meaning to the final result. I haven't found this to be true at all. Commits don't tell me anything other than when the coder left their desk for the moment. When there's a policy that allows people to have a "rough, ugly history", where a coder chooses to commit is completely arbitrary. I would argue that the clean, crafted story is the only helpful one. You can argue that a coder shouldn't be committing unless they are at a natural milestone that can be annotated, but I would consider that the "crafted" story.

u801e 3y ago

> It's an awful shame that GitHub doesn't allow commenting on commit messages. You actually can comment on a commit itself. I'm in the habit on middle-clicking on the sha1 link of commits in a PR and looking at the commit itself. You can comment on lines in the commit, and there's a text area at the bottom where you can comment on the entire commit itself. I'll then follow up with making a comment on the PR linking the commit (pasting the sha1 link) and saying I made a few comments here. > It's as if GitHub is being run by people who just don't know how Git is meant to be used. Github wasn't really designed with code review in mind. A lot of the features they added over the years for review appear to be hacked on rather than fixing fundamental design issues (like being able to comment on commit messages without having to jump through a bunch of hoops). Review systems like gerrit, phabricator, review board, or even email, do a much better job at exposing individual commits and their associated metadata like the commit message.

sverhagen 3y ago
I don't think they were suggesting to review the individual commits, rather the (individual) commit messages. Commit messages are text, so you could have a similar line by line click-and-comment review interface as you already have for the code changes.
- u801e 3y ago
  > I don't think they were suggesting to review the individual commits, rather the (individual) commit messages. That's a good point. > Commit messages are text, so you could have a similar line by line click-and-comment review interface as you already have for the code changes. It would be nice if something like that was available in Github. The closest thing you could do would be to copy the commit title and body and paste it as quoted text in the text area and then comment on it inline.

erhaetherth 3y ago

I write commit messages for future-me. Sooner or later I'm going to encounter the same problem again and wonder how I solved it last time. If I have a vague inkling that I dealt with this before, all I have to do is searching through my commit history and I can find it again. I can search my author (me), I can search by date, I can search by what files I touched. It's lovely.

michaelcampbell 3y ago

> Seriously, as somebody who reviews a lot of code, well-written commit messages are a godsend. This is the issue; are commits in your codebase for the reviewers? Or for FutureDev to see what the hell happened? These are often very different things, and most process models favor one of these at the total expense of the other.

atq2119 3y ago
Interesting that you perceive a dichotomy there, can you elaborate where you see the conflict? As a reviewer, I see myself as a (extremely near, time T+epsilon) future developer who is trying to see what the hell is happening.
- michaelcampbell 3y ago
  There's a dichotomy between a history of actual code changes, oopsies and redos included, and "a carefully crafted story of the intent of this change". One is an ugly reality, the other is a pretty story of intention. The process vs. the final result. Both are useful, but in different contexts. The latter is good for a PR, but when optimized for that often loses a lot of other context, and is meant to be a throwaway bit of data that once the PR is approved, never seen again, nor meant to be seen again. The former can delve a bit into what experiments were tried and abandoned and can give a lot more meaning to the final result. > As a reviewer, I see myself as a (extremely near, time T+epsilon) future developer who is trying to see what the hell is happening I generally find this to not be the case; reviewing is to see what this might "break" and has IME been extremely transactional. Not all PRs nor reviewers are like this of course, and you may not be one. But, again, IME, this is the "modern" workflow.
  - Capricorn2481 3y ago
    > The former can delve a bit into what experiments were tried and abandoned and can give a lot more meaning to the final result. I haven't found this to be true at all. Commits don't tell me anything other than when the coder left their desk for the moment. When there's a policy that allows people to have a "rough, ugly history", where a coder chooses to commit is completely arbitrary. I would argue that the clean, crafted story is the only helpful one. You can argue that a coder shouldn't be committing unless they are at a natural milestone that can be annotated, but I would consider that the "crafted" story.