On 3/30/21 2:57 AM, Junio C Hamano wrote:
All of that can be read from the patch text. What an author is
expected to explain in the proposed commit log message is WHY.
Why is it a good idea to list possible arguments --date can take?
The reason can include "because so far they are not explained
anywhere."
Documentation/SubmittingPatches::describe-changes, especially
[[meaningful-message]], is a good source to learn what a title and a
proposed log message of a patch should look like in this project.
Okay I'll update the patch with proper commit message.
I am not very strongly opposed to extending the tail end of the
existing contents of the file, namely:
ifdef::git-commit[]
In addition to recognizing all date formats above, the `--date` option
will also try to make sense of other, more human-centric date formats,
such as relative dates like "yesterday" or "last Friday at noon".
endif::git-commit[]
and explain what "such as ..." is, but I am fairly negative on
teaching 'tea' to our users before we talk about 2822 and 8601
formats. I actually think the above three lines strikes a good
balance---we do not want the users to be surprised too much when
they see "--date yesterday" to work, but we do not particularly
want to encourage them to use "commit --date noon" [*1*].
Okay so I guess it's better to just extend the tail of the file
to explain a little bit about the relative dates and leave
out the Easter eggs and formats like 'noon' and 'midnight'
Likewise. I am OK with adding (see date-formats) but against
listing the easter eggs as if they are more important than other
forms.
Okay I'll just add the (see date-formats) and leave out the
exhaustive list.
[Footnote]
*1* The approxidate is useful when a rough "around that time"
specification suffices, e.g. "git log --since='last.week'". The
user is OK to see commits down to roughly a week old, and would
not be upset if a commit with a timestamp that is 9 days old
shown.
On the other hand, it would be unusual that somebody cares
enough to use "git commit --date" but yet it is OK that the time
recorded is fuzzy. For that reason alone, I am in general
negative on the direction this patch tries to take us in.
So according to you, is it a relevant/worthwhile change
to add in docs?
Thanks.
