4 ms·
Is this example too large or about the right size for you? https://github.com/simonw/sqlite-utils/commit/ab8d4aad0c42f905640981f6f24bc1e37205ae62 https://github
by simonw 4y ago
Is this example too large or about the right size for you? https://github.com/simonw/sqlite-utils/commit/ab8d4aad0c42f905640981f6f24bc1e37205ae62 https://github.com/simonw/sqlite-utils/commit/ab8d4aad0c42f9...
- donatj 4y agoThat's probably fine, honestly. I'd maybe take a little more context in the message, but I certainly write messages like that myself. It's always later when I'm looking into problems that I want more context. I spend a lot of time hunting down problems. Half the time I caused them. I know tone/angle of commit messages is an entirely separate bag of cats that people have strong opinions about, but I find the tone strange. I generally fond of commits that state what the commit does. Something along the lines of "Adds optional table support"
- js2 4y ago> Adds optional table support Ahem, "Add optional table support" Because: imperative mood. :-) I was an early git contributor and I've modeled my commits from the git project ever since.
- simonw 4y agoI can never remember which tense is recommended for git commits - I keep meaning to figure that out and try to make a habit of if.
- mklein994 4y agoIt's called the Imperative Mood[0]. I like to think of it as though I'm completing this statement: "If you apply this patch, this commit will [Do The Thing™]". Here's a few examples: If I were to apply this patch, this commit will… - Simplify FooWidget - Add optional table support - Remove trailing whitespace - Update fizzbuzz to 1.2.0 - Merge branch 'feature/ABC-123-foobar' - Revert "Add foo to bar" [0]: https://en.wikipedia.org/wiki/Imperative_mood https://en.wikipedia.org/wiki/Imperative_mood
- simonw 4y agoThanks, that's a really clear explanation. I'm going to try that out and see if it sticks for me.
- fragmede 4y agoThe commit message could stand to be the tiniest bit longer, instead of having to click through to find out what #299 is.
- js2 4y agoHere's what I would have written. This took me reading the code and clicking through to #299 to figure out and could have been in the commit message: Add optional tables argument to schema command The schema of every table in the DB is shown by default. Add optional tables argument to restrict which tables are shown. Closes #299
- thunky 4y agoThe issue serves no purpose for me, so here's a shorter version: Add `tables` argument to schema command Optionally restricts which tables are shown
- js2 4y agoI think the issue was originally an outside feature request and adding "Closes #xxx" is there just to link the commit to the issue and automatically close it.
- thunky 4y agoIt wasn't, actually. simonw created the issue himself and self-closed it 8 minutes later. I had a conversation with simonw yesterday about why I personally view this as an anti-pattern: https://news.ycombinator.com/item?id=33388369 https://news.ycombinator.com/item?id=33388369
- seadan83 4y agoI really love this specific thread, thank you all for the thoughtful commentary. An experience that is really burned into me was working on a team that put very little into commit comments or PR descriptions. But, they did have debates and design decision conversations within PR review comments. Hence the context was in the PR comments. One fine day, I was looking for the background behind some code while tracking down a problem. After identifying about 7 commits (with pretty basic/useless messages, and no PR link!), I then had to find the corresponding PRs based on timestamps, and search the PR history for PRs merged around those timestamps. From there, i had to review the conversations, some very lengthy back and forth conversation threads within the PRs to happily finally find a conversation that had the desired background. Fhe background was something like "why did you do this? X reason. Response: ok" Given that was the main thrust of the update, had that context been in the commit, it would have saved a solid hour. From this experience and others tracking down N jira items to gain context into N possible commits, my rule of thumb is that it scales poorly if you have to go to an external tool to gain context. The above experience meant tracking down the context of any one change was generally a 15 to 60 minute exercise! No chance to grep logs, just a lot of timestamps searches and scrolling through PR conversations. My preferred approach is that a first commit is "for the history." Any further commits are for the reviewer and when squashed those commit comment will generally be removed. So things like "address concern for X" and "formatting" makes sense for a reviewer coming back to an already reviewed PR, but is deleted fir someone that will look at it squashed. The idea being the squashed commit is on master, at that point nobody cares about a "formatting" commit that is one line in a series of 10 other similar commits (that person is tracking down a bug or trying to figure out non-obvious code, they do not care about renamed variables being apart from other tweaks and formatting) Hence, there is different granularity in commits, but eventually the PR and commit granularity become the same. I thus treat PRs as ephemeral with all of the initial PR text auto-generated from the commits. So, any long work to fill out a PR description instead is captured in the commit message which then autopopulates the PR description leaving nothing extra in the PR. Then any review comments are preferably not addressed directly in the PR, but with a preference to update the code for clarity or with needed documentation. Once that is done, the response to the reviewer is a "updated in git Sha X, WDYT?" Hence, the PR is for the review process, not documentation. Of course, some updates need several commits to be grok-able in review. In this case PRs are broken up, a leading PR might be 10 refactoring commits which is then squashed together with title "refactoring X", and the lusg of commits then automatically squashed into a list of reactors done in that commit. Thus avoids a very long string of commits in the history. Then the 11th commit that is the actual bug fix or functionality changes is submitted and then exists in the history as it's own commit. So the history would be like "simplify login moodule\n[list of refactors", and commit two: "fix empty username login problem\n[description of why this is a fix]"