Oh wow I did not know that the -t option even existed. Do you know of any resources @bootcode
that is similar to what your template workflow looks like?
Happy it helps. No specific commenting workflow. Interestingly there are hits
out there about git comments, but they mostly cover formatting. That's nice
(and do read definitely), but the focus should be on content first, formatting
second. I can live with the title ending in a dot, sorry :)
What is more interesting is the content of the message. If we are limited to a single line (as with -m), too much interesting detail gets lost.
The commit message should give context for the unfamiliar reader. Imagine someone searching for the cause of a bug, going through all changes made in a given interval. A good commit message can reveal if there's something relevant in there or not.
The message should include:
First line with brief description of change.
Purpose of the change.
Broader context of the change.
Follow-up work to expect.
How the reviewer can try the change
command for batch stuff
demo url or screenshot for UI changes
How the change was tested (if not apparent from CI)
For example:
Add initial support for undotted section numbers.
This change lets us roll out support for FooBarQuux documents in English.
Normally section numbers in FooBar documents are followed by dots. But in
FooBarQuux, there's a special convention to make section numbers undotted.
Note: the undotted numbers increase monotonically and don't get reset by
intertwining higher-level headings. While not forbidden, Table Of Contents
consumers might not expect this situation. So rollout should be gradual to
catch any errors.
This is part of the broader effort tracked in bug/55443 about migrating away
from plain FooBar documents.
Follow-up change will add support for three more languages, also increase test
coverage. Once German is supported, bug/12345 will be unblocked.
I also added a tool for quick experimentation on the test corpus. Example
usage:
bazel build //foo/bar:quux
./bazel-bin/foo/bar/quux --input_dir=/bog --language=en --summary_only
TESTED=checked corpus with tool, ran integration tests
The commit message also acts as a test of the rationale. It happened to me multiple times that I took 2 hours writing a change, then while phrasing the rationale part of the commit message it dawned on me Ouch. Actually this is not the right approach for that purpose.
As for a general git usage model, I use the nvie model with content.
If you would like to hear more of such info, don't forget to follow me here directly, or subscribe to updates about my book Programming Without Anxiety.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
Oh wow I did not know that the
-toption even existed. Do you know of any resources @bootcode that is similar to what your template workflow looks like?Happy it helps. No specific commenting workflow. Interestingly there are hits
out there about git comments, but they mostly cover formatting. That's nice
(and do read definitely), but the focus should be on content first, formatting
second. I can live with the title ending in a dot, sorry :)
What is more interesting is the content of the message. If we are limited to a single line (as with
-m), too much interesting detail gets lost.The commit message should give context for the unfamiliar reader. Imagine someone searching for the cause of a bug, going through all changes made in a given interval. A good commit message can reveal if there's something relevant in there or not.
The message should include:
For example:
The commit message also acts as a test of the rationale. It happened to me multiple times that I took 2 hours writing a change, then while phrasing the rationale part of the commit message it dawned on me Ouch. Actually this is not the right approach for that purpose.
As for a general git usage model, I use the nvie model with content.
If you would like to hear more of such info, don't forget to follow me here directly, or subscribe to updates about my book Programming Without Anxiety.