Re: [PATCH] doc: simplify man version
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Apr 11, 2023, 16:30 UTC
- Message-ID
- <xmqqwn2i9ybb.fsf@gitster.g>
- In-Reply-To
- <64349c7dc4f49_7452943c@chronos.notmuch>
Felipe Contreras <felipe.contreras@gmail.com> writes:
Show 21 quoted lines
> Junio C Hamano wrote: >> Felipe Contreras <felipe.contreras@gmail.com> writes: >> >> > diff --git a/Documentation/Makefile b/Documentation/Makefile >> > index a6ba5bd460..4721b000c1 100644 >> > --- a/Documentation/Makefile >> > +++ b/Documentation/Makefile >> > @@ -150,8 +150,7 @@ ASCIIDOC_HTML = xhtml11 >> > ASCIIDOC_DOCBOOK = docbook >> > ASCIIDOC_CONF = -f asciidoc.conf >> > ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \ >> > - -amanversion=$(GIT_VERSION) \ >> > - -amanmanual='Git Manual' -amansource='Git' >> > + -amanmanual='Git Manual' -amansource='Git $(GIT_VERSION)' >> > ASCIIDOC_DEPS = asciidoc.conf GIT-ASCIIDOCFLAGS >> > TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML) >> > TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK) >> >> Is this a complete patch, > > Yes it is complete.
Good.
Show 6 quoted lines
> I don't know know what could give this impression, given that a link to > the documentation and the link to the source code was given: > ... > The code clearly tests for empty strings: > > test="not($Name = '') and not($Version = '')
This part is exactly what I meant. The readers of "git log" shouldn't have to dig to external source material and find that line to convince themselves why this is safe thing to do.
> And it's not clear to me what else it would be checking for.
Good. The job of reviewers is not about nitpicking, but work with and help a patch author to polish the patch text (both proposed log message or diff) by pointing out what the author may have thought obvious to everybody, because it was obvious to the author, but may not be so obvious. The goal is not to convince reviewers how the patch text is correct in review discussion thread. The goal is to use reviewers' input to identify such parts of the patch text that needs clarifying and update the patch text. It is to avoid future readers of "git log -p" to ask the same question, because unlike reviewers, they will not have the original author readily available to answer their questions.
Thanks.