Re: [PATCH] doc: doc-diff: specify date

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: May 8, 2023, 02:08 UTC
Message-ID: <645859a541f23_4e612944b@chronos.notmuch>
In-Reply-To: <xmqq8re3inn4.fsf@gitster.g>

Junio C Hamano wrote:

Show 15 quoted lines

> Felipe Contreras <felipe.contreras@gmail.com> writes:
> 
> > Otherwise comparing the output of commits with different dates generates
> > unnecessary diffs.
> >
> > Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
> > ---
> >  Documentation/doc-diff | 1 +
> >  1 file changed, 1 insertion(+)
> 
> Ahh, it is a fix for a fallout from 28fde3a1 (doc: set actual
> revdate for manpages, 2023-04-13); when it is shown in the patch
> form like this, it is kind of obvious why we need to compensate for
> that change this way, but apparently "doc-diff" slipped everybody's
> mind back then when we were looking at the change.

Yes. doc-diff is an odd duck, because it can't be easily integrated to the testing framework.

Sometimes a diff in the documentation is intentional, so the fact that doc-diff generates an output from HEAD~ to HEAD is precisely what was intended. However, sometimes it's not. Maybe a flag inside the commit message such as GitHub's `[no ci]` might help, but it's beyond me how could that be cleanly integrated to continous integration machinery.

For now doc-diff is meant to be run manually, therefore it's expected that some unexpeced diffs are inevitably going to slip by, and more relevantly: issues in doc-diff itself are going to slip by.

Show 6 quoted lines

> Looking at the patch text of 28fde3a1, we pass GIT_VERSION and
> GIT_DATE to AsciiDoc since that version.  We were already covering
> GIT_VERSION by hardcoded "omitted" string, and now we compensate for
> the other one here, which means this change and the other changes
> complement each other, and there shouldn't be a need to further
> adjustment for that change around this area.  Looking good.

Yes. I think we should be passing a semi-real version instead, like `0.0.0`, just to see how a real version would look like, but that's orthogonal.

Show 15 quoted lines

> > diff --git a/Documentation/doc-diff b/Documentation/doc-diff
> > index 1694300e50..554a78a12d 100755
> > --- a/Documentation/doc-diff
> > +++ b/Documentation/doc-diff
> > @@ -153,6 +153,7 @@ render_tree () {
> >  		make -j$parallel -C "$tmp/worktree" \
> >  			$makemanflags \
> >  			GIT_VERSION=omitted \
> > +			GIT_DATE=1970-01-01 \
> >  			SOURCE_DATE_EPOCH=0 \
> >  			DESTDIR="$tmp/installed/$dname+" \
> >  			install-man &&
> 
> I wonder what the existing SOURCE_DATE_EPOCH was trying to do there,
> though.

I also wondered the same, but again: orthogonal.

Cheers.

-- 
Felipe Contreras