document prompt for formatting good git-commit subjects. #232
Conversation
| @@ -5,6 +5,8 @@ | |||
| # | |||
| # <footer> | |||
| # | |||
| # ** A good message should complete this sentence: when applied, this commit will... ** | |||
There was a problem hiding this comment.
Should you replace the word "message" with "subject" (like you did in the README) to help clarify the recommendation is not for commit body/footer?
From a similar article:
Remember: Use of the imperative is important only in the subject line. You can relax this restriction when you’re writing the body.
There was a problem hiding this comment.
We do mention in the README here that the body should use an imperative tone, but it seems like this Chris Beams guy says it doesn't need to be as strict. https://github.com/sparkbox/standard/blob/ab244d2331a527eb12dbd05febd30ddb1b0b1cfc/code-style/git/README.md#the-body
| @@ -117,7 +117,8 @@ Find the [allowed types above](#Allowed-Values-for-Types). | |||
|
|
|||
| An [imperative tone][365] is also helpful in conveying what a commit does, | |||
| rather than what it did. For example, use **change**, not _changed_ or | |||
| _changes_. | |||
| _changes_. To put it another way: a good subject should complete this sentence: | |||
| ["when applied, this commit will..."][drew-devault-link] | |||
There was a problem hiding this comment.
I think this type of prompt is really helpful. I'm trying to put myself in the committer's shoes and see how this changes my instincts.
when applied, this commit will...
Adds dependabot configadds XYZController
I'm not sure this commit will puts my focus on what the commit changes.
If we switched the wording a little to when this commit is applied, ____
Dependabot is run every dayXYZController handles /xyz/Users can see their XYZs
It's not perfect either, but I felt like it took the focus away from what the commit does, which is clear in the diff.
There was a problem hiding this comment.
I like either prompt.
Is the issue that this prompt necessitates filling out the body in a useful way? Do we need to add a prompt for the body too?
There was a problem hiding this comment.
I've been trying out the above when this commit is applied, ___ to help me write better commit subjects recently. I think using this commit will __ makes you use a verb to start the subject like "add", "fix", "remove" which I can see in @cromwellryan's opinion could state the obvious if you looked at the code to see what was added or removed. Using when this commit is applied can help you focus more on the impact of removing or adding code. For instance, now that we added a Dependabot config, the impact is that Dependabot will run every week. I'm sure there are times when using a verb like "add" or "remove" would be sufficient in some cases too like when we remove peoples ssh keys from a repo.
All this is to stay that I think I like when this commit is applied, ____ a little bit better.
I don't think we need a prompt for the body. We already mention that it should explain the "why".
From the referenced article:
https://chris.beams.io/posts/git-commit/
Use the body to explain what and why vs. how
|
This PR is a couple months old now, but as I'm getting up to speed on "the Sparkbox way" to do git, are there any new thoughts on this? @jordanleven |
|
@bengoshow not that I'm aware of. The general advice of this PR is valid, the semantics are what we're discussing, so if the advice is useful great! :) |
No description provided.