[docs] doc: enhance SRCREV_FORMAT description

Adding documentation for having an empty first component for the
SRCREV_FORMAT.

Signed-off-by: Patrick Vogelaar <patrick.vogelaar.dev@mailbox.org>
---
 .../bitbake-user-manual-ref-variables.rst                   | 6 ++++++
 1 file changed, 6 insertions(+)

On Wed Sep 10, 2025 at 4:54 PM CEST, Patrick Vogelaar via lists.yoctoproject.org wrote:
> Adding documentation for having an empty first component for the
> SRCREV_FORMAT.
>
> Signed-off-by: Patrick Vogelaar <patrick.vogelaar.dev@mailbox.org>
> ---
>  .../bitbake-user-manual-ref-variables.rst                   | 6 ++++++
>  1 file changed, 6 insertions(+)
>
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
> index 810f88689..07e754096 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
> @@ -1670,6 +1670,12 @@ overview of their function and contents.
>        ``AUTOINC`` placeholder is added and if needed. And, this placeholder
>        is placed at the start of the returned string.
>  
> +      The :term:`SRCREV_FORMAT` can also take the form "_component2".
> +      This assumes that there is a component in the :term:`SRC_URI` that does not
> +      have a name assigned. While this is not considered good practice, it can be
> +      usefull if a ``.bbappend`` file needs to extend the :term:`SRC_URI` with

s/usefull/useful/

> +      an additional repository.
> +
>     :term:`STAMP`
>        Specifies the base path used to create recipe stamp files. The path
>        to an actual stamp file is constructed by evaluating this string and

This is not a good practice, albeit useful. So what is the good practice, in the
case where I _do_ want an additional git remote source to be fetched? Modify
the original SRC_URI to include a name for the first component, and do 

SRCREV_FORMAT = "component1_component2"

as usual?

This doesn't sound practical so I'm leaning towards your solution. But if this
is something we should really never do, then I'm wondering if we should document
it here…

Antonin

> Antonin Godard via lists.openembedded.org <antonin.godard=bootlin.com@lists.openembedded.org> hat am 12.09.2025 17:02 CEST geschrieben:
> 
>  
> On Wed Sep 10, 2025 at 4:54 PM CEST, Patrick Vogelaar via lists.yoctoproject.org wrote:
> > Adding documentation for having an empty first component for the
> > SRCREV_FORMAT.
> >
> > Signed-off-by: Patrick Vogelaar <patrick.vogelaar.dev@mailbox.org>
> > ---
> >  .../bitbake-user-manual-ref-variables.rst                   | 6 ++++++
> >  1 file changed, 6 insertions(+)
> >
> > diff --git a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
> > index 810f88689..07e754096 100644
> > --- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
> > +++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
> > @@ -1670,6 +1670,12 @@ overview of their function and contents.
> >        ``AUTOINC`` placeholder is added and if needed. And, this placeholder
> >        is placed at the start of the returned string.
> >  
> > +      The :term:`SRCREV_FORMAT` can also take the form "_component2".
> > +      This assumes that there is a component in the :term:`SRC_URI` that does not
> > +      have a name assigned. While this is not considered good practice, it can be
> > +      usefull if a ``.bbappend`` file needs to extend the :term:`SRC_URI` with
> 
> s/usefull/useful/
> 
> > +      an additional repository.
> > +
> >     :term:`STAMP`
> >        Specifies the base path used to create recipe stamp files. The path
> >        to an actual stamp file is constructed by evaluating this string and
> 
> This is not a good practice, albeit useful. So what is the good practice, in the
> case where I _do_ want an additional git remote source to be fetched? Modify
> the original SRC_URI to include a name for the first component, and do 
> 
> SRCREV_FORMAT = "component1_component2"
> 
> as usual?
> 
> This doesn't sound practical so I'm leaning towards your solution. But if this
> is something we should really never do, then I'm wondering if we should document
> it here…

Thanks for the feedback Antonin. When going back to the code and checking what is commonly used and what isn't, I stumbled over a few interesting things. I might need to change it a bit more to reflect it correctly (The proposal now might not be correct). I will do an update of the patch and consider your input.

Patrick 

> 
> Antonin
> 
> -- 
> Antonin Godard, Bootlin
> Embedded Linux and Kernel engineering
> https://bootlin.com
> 
> 
> -=-=-=-=-=-=-=-=-=-=-=-
> Links: You receive all messages sent to this group.
> View/Reply Online (#18012): https://lists.openembedded.org/g/bitbake-devel/message/18012
> Mute This Topic: https://lists.openembedded.org/mt/115170994/10013339
> Group Owner: bitbake-devel+owner@lists.openembedded.org
> Unsubscribe: https://lists.openembedded.org/g/bitbake-devel/unsub [patrick.vogelaar.dev@mailbox.org]
> -=-=-=-=-=-=-=-=-=-=-=-