5 ms·
This seems like a really bad idea. I put a lot of effort into commit messages and try to always give a good summary of what (and more importantly why) the chan
by peterkelly 4y ago
This seems like a really bad idea.
I put a lot of effort into commit messages and try to always give a good summary of what (and more importantly why) the change was made. I consider it almost as important as the code itself, because it serves as a form of documentation, as well as a way of communicating to both other team members and my future self.
I struggle immensely with writing normal documentation, whether it be fine-grained stuff like descriptions of functions/classes, or higher-level architectural issues (I have written a PhD thesis so I can do it, it's just a tremendously difficult undertaking). I treat commit messages like a second best alternative to code documentation, and they're a lot easier to write because all the information is fresh in my head at the time I make a commit. A good log can also serve as a solid starting point for later writing other forms of documentation.
Git is designed as a decentralised version control system; pull requests are something that the major repository hosting providers have added, and while I appreciate the existence of those features I'd rather not rely on them at least in terms of the long-term record for a project. In the case of pull requests, someone who is already writing detailed commit messages basically has double the work if they want to communicate the same kind of information in pull request descriptions/comments, though you can just make the comments a copy of the log (BitBucket does this). And if you want to migrate from one provider to another you can lose all this extra context that is not in the repository itself.
Other than attempt to increase lock-in, I don't understand why they would make this change, and it seems like it's based on assumptions about how some teams use git without taking into account other styles - there's considerable variety in practices between teams and for those that rely on the commit messages more heavily this seems like it's going to make for a worse experience.
- drey08 4y agoThis is about commit comments, not commit messages.
- peterkelly 4y agoAh, thanks for the clarification. This was definitely not obvious to me from their announcement and I wouldn't be surprised if others similarly misinterpret it.
- politelemon 4y agoIt was very obvious to me, it's right at the top of the page. > Note: This change does not impact regular review comments or other comments made directly on a pull request.
- rpdillon 4y agoI had the same confusion as gp and spent a couple of minutes resesrching to figure it out. The reason the above quote didn't help me is that is clarifies that this isn't about review comments or other PR comments. But commit messages are neither of those. Root cause? I didn't even know commit comments were a thing that GitHub had! I assume it was much clearer to everyone that knew about them.
- peterkelly 4y ago> Root cause? I didn't even know commit comments were a thing that GitHub had! Me too. It wasn't a term or feature I was familiar with, and (incorrectly) assumed they were talking about commit messages.
- 8note 4y agoHow do you test that the commit messages are accurate over time for what the software does? Anytime Ive done code archaeology, the commit messages, no matter how detailed, have been irrelevant to what's currently running. Between reading a book of commit comments, or the authoritative code, it's much more efficient to just read the code. One of the big things with commit messages is that they won't capture changes in adjacent systems that don't share a code base. While you can spot weird edge cases in the code, you can't from the commit messages alone
- peterkelly 4y agoOh, they don't remain accurate over time. The point is to capture what is true at the time the commit is made, and in aggregate to tell a story of the code's evolution. If someone wants to know why a particular thing is done the way it is, then this can provide insights as to how it got that way and why. I don't regard a commit log as an adequate substitute for documentation on the latest version of a codebase. Rather, it can provide a useful starting point for writing documentation that I find easier than beginning from a "blank page" so to speak. It's a starting point only - there's a lot of work required to get from that point to an accurate description of the most recent version of a codebase. I agree with your point about changes in adjacent systems, though where that happens I try to mention those changes in the commit message and explain how they relate to the commit itself. I'm speaking mostly from experience working on software that exists in a single repository; for things that are split among multiple independent repositories/services I agree it's more difficult (and this is why i prefer monorepos whenever its viable).