From: Patrick Steinhardt <ps@pks.im>
Date: Mon, 03 Jun 2024 07:37:02 GMT
Subject: Re: [PATCH v3 12/12] builtin/refs: new command to migrate ref storage formats
Message-ID: <Zl1ynntoW-_VzvY-@framework>
In-Reply-To: <xmqq7cf8b1gg.fsf@gitster.g>

On Sat, Jun 01, 2024 at 06:03:27PM -0700, Junio C Hamano wrote:
> Junio C Hamano <gitster@pobox.com> writes:
> 
> > One thing missing is an entry in command-list.
> >
> > If you ran "make check-docs", you would have seen
> >
> >     $ make check-docs
> >     no link: git-refs
> >
> > The Documentation/MyFirstContribution.txt file does mention
> > command-list, but it is rather messy and unorganized.  I think the
> > checklist at the top of <builtin.h> would be the best source of
> > information at this moment.
> >
> > Thanks.
> 
> You'd need something like this.  
> 
> With the command missing from command-list.txt, git.1 (which has the
> list of commands) will fail to mention the command, of course.
> 
> The fix to the documentation file itself is also crucial, as the
> name section is where we grab the list of command descriptions used
> in "git help -a", and with the extra blank line, git.1 will fail to
> build.

Thanks, I'll squash this in and send a new version.

It would of course be great if CI had noticed this. And we do execute
`make check-docs` via "ci/test-documentation.sh" indeed. But the problem
is that `make check-docs` does not return an error when there is a
missing link.

I'll send a follow-up for this test gap later this week.

Patrick