Re: [yocto-docs][PATCH v2] Update the documentation for SRCPV

["Antonin Godard" <antonin.godard@bootlin.com>]

Hi Quentin,

On Mon Nov 25, 2024 at 4:57 PM CET, Quentin Schulz wrote:
> Hi Antonin,
>
> On 11/25/24 9:17 AM, Antonin Godard wrote:
>> The variable SRCPV is deprecated since 4.3. Instead of including SRCPV
>> in PV, including the sign "+" is enough for bitbake to add the source
>> control information to PKGV during the packaging phase.
>> 
>> Update the documentation for SRCPV and the places where it was used.
>> When instructions previously referred to SRCPV, replace by mentioning to
>> include "+" in the assignment.
>> 
>> In most examples, "+git" is added to PV as it is the most popular SCM.
>> Simply adding "+" is also possible, although it is better practice to
>> include the SCM name, so give that example.
>> 
>> Update the gcompat example with l3afpad as it didn't include "+git" in
>> its PV definition anymore.
>> 
>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>> ---
> [...]
>> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
>> index ec4d7ab73fe3ac1bc64f5378c65d19ae0b749809..f611edae9f37097734234805faa34b1850e5cfd1 100644
>> --- a/documentation/ref-manual/variables.rst
>> +++ b/documentation/ref-manual/variables.rst
>> @@ -209,12 +209,11 @@ system and gives an overview of their function and contents.
>>            SRCREV = "${AUTOREV}"
>>   
>>         If you use the previous statement to retrieve the latest version of
>> -      software, you need to be sure :term:`PV` contains
>> -      ``${``\ :term:`SRCPV`\ ``}``. For example, suppose you have a kernel
>> -      recipe that inherits the :ref:`ref-classes-kernel` class and you
>> -      use the previous statement. In this example, ``${SRCPV}`` does not
>> -      automatically get into :term:`PV`. Consequently, you need to change
>> -      :term:`PV` in your recipe so that it does contain ``${SRCPV}``.
>> +      software, you need to make sure :term:`PV` contains the ``+`` sign so
>> +      :term:`bitbake` includes source control information to :term:`PKGV` when
>> +      packaging the recipe. For example::
>> +
>> +        PV = "6.10.y+git"
>>   
>
> I believe this is not properly indented? Missing a space here to follow 
> our standards?


Good catch, thank you. Some others below are also not properly indented. It
would be nice if sphinx-lint could report this, but I don't think it is able to.

>>         For more information see the
>>         ":ref:`dev-manual/packages:automatically incrementing a package version number`"
>> @@ -5152,7 +5151,7 @@ system and gives an overview of their function and contents.
>>         The :term:`LINUX_VERSION` variable is used to define :term:`PV`
>>         for the recipe::
>>   
>> -         PV = "${LINUX_VERSION}+git${SRCPV}"
>> +         PV = "${LINUX_VERSION}+git"
>>   
>>      :term:`LINUX_VERSION_EXTENSION`
>>         A string extension compiled into the version string of the Linux
>> @@ -6720,9 +6719,10 @@ system and gives an overview of their function and contents.
>>         For example, consider two recipes ``foo_1.2.bb`` and ``foo_git.bb``
>>         where ``foo_git.bb`` contains the following assignment::
>>   
>> -         PV = "1.1+git${SRCPV}"
>> +         PV = "1.1+git${@bb.fetch2.get_srcrev(d)}"
>>   
>
> Getting back at my original comment in v1 (forgot to answer again there, 
> so doing it here). I'm not sure this makes sense as an example as it is 
> not necessary anymore since + character is enough to include that 
> information in PKGV (as far as I understood from the patch). I would 

Exactly, "+" is enough now.

> like to avoid suggesting using something that isn't relevant here (or 
> discouraged).
>
> I think we could simplify the example. The point is not necessarily to 
> use % with a git-named recipe but rather that a git-named recipe is not 
> going to match "git" but the "PV" defined in the recipe. What do you think?

Ok, something like:

  If your PV is equal to "a.b.c+git", you can match it with "a.b.c%" in
  PREFERRED_VERSION?

This makes more sense with the current state of things, and simplifies the
example a bit.

> Otherwise, I don't really know what kind of example we could provide 
> that would match the state before the + character behavior change.
>
> Looks good otherwise!

Thanks!
Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com