Re: [PATCH bpf-next] scripts/bpf: Fix attributes for bpf-helpers(7) man page

[Quentin Monnet <quentin@isovalent.com>]

On 23/08/2022 16:04, Alejandro Colomar wrote:
> Hi Quentin,
> 
> On 8/23/22 16:23, Quentin Monnet wrote:
>> Wow, I'm two days late!
> 
> ;-)
> 
> [...]
>>>
>>> You could append the version here.  Or maybe put a placeholder that the
>>> script should fill with information from the makefile or
>>> git-describe(1)?
>>
>> So if I understand correctly, running bpf_doc.py should currently
>> produce the following string:
>>
>>      .TH BPF-HELPERS 7 "" "Linux (5.19.0)" ""
>>
>> Is this what you expect?
> 
> Almost.  I expect:
> 
> .TH BPF-HELPERS 7 "" "Linux 5.19.0"
> 
> Notice the differences:
> - No 5th empty field "".
> - No parentheses in the version string.
> 
> But since you're not in control of the last field, and it's just a bug
> in rst2man, an empty 5th arg as you suggested is the best you can
> provide.

Agreed

>  I'll file the bug.
> 
> As for the parentheses in the version, I wouldn't put them; I only put
> them in the man-pages unreleased string, to make it clear that it's a
> version, but in the final version I remove them.

OK, I wasn't sure. Thanks for the details.

> See:
> 
> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/lib/version.mk>
> and
> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/lib/dist.mk#n33>
> 
>>
>> I can make the script call "make kernelversion" to produce the above.
>> I'm not 100% convinced it should be the role of that script vs. when
>> copying it (we risk having some inaccuracies, for example I generated
>> the above from the bpf-next, so it doesn't really correspond to 5.19),
>> but maybe it's easier that way and avoids adding another script in the
>> middle of the generation so OK.
> 
> I like it that way.  Moreover, I'll always run this script from a
> release tag from Linus' repo, so the version should match exactly the code.
> 
> Anyway, and I think this affects many projects out there have the same
> issue:
> 
> The versioning should always be correct.  git-describe(1) should be
> preferred, or in absence of that, a generic (unreleased) string should
> be used.  Describing any commit after v5.18 and before v5.19-rc1 to be
> '5.18.0' is plain wrong/misleading.  The Makefile should probably
> autogenerate that info from git-describe(1).  See how the Linux
> man-pages do it (in the links above you can see it) for example.

It's not really about how to do it, more that I don't want to have a
hard dependency on git for the script. I want it to run just as well
when there's no Git repo around. But I can try to run "git describe" and
fall back on the Makefile (or on an empty version) if the command fails.

OK I'll prepare a new version, thanks for your help.
Quentin