[2/3] doc: bitbake-user-manual: AUTOREV and SRCREV_FORMAT roles in fetching

Describe the roles of AUTOREV and SRCREV_FORMAT in the fetching step.
Add their missing descriptions to the variable reference section.

Fixes [YOCTO #14498]

Signed-off-by: Adam Blank <adam.blank.g@gmail.com>
---
 .../bitbake-user-manual-fetching.rst          | 46 ++++++++++++++++++-
 .../bitbake-user-manual-ref-variables.rst     | 15 ++++--
 2 files changed, 56 insertions(+), 5 deletions(-)

On Tue Oct 21, 2025 at 8:28 PM CEST, Adam Blank via lists.openembedded.org wrote:
> Describe the roles of AUTOREV and SRCREV_FORMAT in the fetching step.
> Add their missing descriptions to the variable reference section.
>
> Fixes [YOCTO #14498]
>
> Signed-off-by: Adam Blank <adam.blank.g@gmail.com>
> ---
>  .../bitbake-user-manual-fetching.rst          | 46 ++++++++++++++++++-
>  .../bitbake-user-manual-ref-variables.rst     | 15 ++++--
>  2 files changed, 56 insertions(+), 5 deletions(-)
>
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
> index d10d2f611..dbb52e85a 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
> @@ -173,6 +173,11 @@ govern the behavior of the unpack stage:
>  -  *subdir:* Unpacks the specific URL to the specified subdirectory
>     within the root directory.
>  
> +-  *name:* Assigns a name to a given component of the :term:`SRC_URI`.
> +   This component is later referenced by this name when specifying its
> +   :term:`SRCREV` or :term:`SRC_URI` checksum, or to correctly place its
> +   revision in the package version string with aid of :term:`SRCREV_FORMAT`.
> +
>  The unpack call automatically decompresses and extracts files with ".Z",
>  ".z", ".gz", ".xz", ".zip", ".jar", ".ipk", ".rpm". ".srpm", ".deb" and
>  ".bz2" extensions as well as various combinations of tarball extensions.
> @@ -453,7 +458,7 @@ This fetcher supports the following parameters:
>     By default, the path is ``git/``.
>  
>  -  *"usehead":* Enables local ``git://`` URLs to use the current branch
> -   HEAD as the revision for use with ``AUTOREV``. The "usehead"
> +   HEAD as the revision for use with :term:`AUTOREV`. The "usehead"
>     parameter implies no branch and only works when the transfer protocol
>     is ``file://``.
>  
> @@ -845,4 +850,41 @@ submodules. However, you might find the code helpful and readable.
>  Auto Revisions
>  ==============
>  
> -We need to document ``AUTOREV`` and :term:`SRCREV_FORMAT` here.
> +For recipes which need to use the latest revision of their source code,
> +the way to achieve it is to use :term:`AUTOREV` as the value of the
> +source code repository's :term:`SRCREV`::
> +
> +   SRCREV = "${AUTOREV}"
> +
> +.. note::
> +
> +   With :term:`AUTOREV`, BitBake will always need to take the additional step of
> +   querying the remote repository to retrieve the latest available revision.
> +
> +   Also, recipes using it don't benefit from the caching mechanism.
> +
> +Multiple Source Control Repositories
> +====================================
> +
> +For some recipes it is necessary to make use of more than one
> +version controlled source code repository. In such case, the recipe
> +must provide BitBake with information about how it should include
> +the different SCM revisions in its package version string, instead of its
> +usual approach with a single :term:`SRCREV`.
> +
> +For this purpose, the recipe must set the :term:`SRCREV_FORMAT`
> +variable. Consider the following example::
> +
> +   SRC_URI = " \
> +       git://git.some.example.com/source-tree.git;name=machine \
> +       git://git.some.example.com/metadata.git;name=meta \
> +       "
> +   SRCREV_machine = "3f9db490a81eeb0077be3c5a5aa1388a2372232f"
> +   SRCREV_meta = "1ac1d0ff730fe1dd1371823d562db8126750a98c"
> +   SRCREV_FORMAT ?= "meta_machine"
> +
> +The value given to :term:`SRCREV_FORMAT` references names, which were
> +assigned using the ``name`` parameter in the :term:`SRC_URI` definition,
> +and which represent the version controlled source code repositories.
> +In the above example, the :term:`SRC_URI` contained two URLs named
> +"meta" and "machine".
> 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 e50b71380..7c864b69a 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
> @@ -36,6 +36,14 @@ overview of their function and contents.
>        when specified allows for the Git binary from the host to be used
>        rather than building ``git-native``.
>  
> +   :term:`AUTOREV`
> +      This is a special variable used during fetching. When :term:`SRCREV` is
> +      set to the value of this variable, the latest revision from the version
> +      controlled source code repository is used.
> +      It should be set as follows::
> +
> +         SRCREV = "${AUTOREV}"
> +
>     :term:`AZ_SAS`
>        Azure Storage Shared Access Signature, when using the
>        :ref:`Azure Storage fetcher <bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`
> @@ -1622,7 +1630,8 @@ overview of their function and contents.
>  
>        -  ``name``: Specifies a name to be used for association with
>           :term:`SRC_URI` checksums or :term:`SRCREV` when you have more than one
> -         file or git repository specified in :term:`SRC_URI`. For example::
> +         file or source control repository specified in :term:`SRC_URI`.
> +         For example::
>  
>              SRC_URI = "git://example.com/foo.git;branch=main;name=first \
>                         git://example.com/bar.git;branch=main;name=second \
> @@ -1657,11 +1666,11 @@ overview of their function and contents.
>        identifier and not just a tag.
>  
>     :term:`SRCREV_FORMAT`
> -      Helps construct valid :term:`SRCREV` values when
> +      Helps construct a valid package version string when
>        multiple source controlled URLs are used in
>        :term:`SRC_URI`.
>  
> -      The system needs help constructing these values under these
> +      The system needs help constructing this value under these
>        circumstances. Each component in the :term:`SRC_URI` is assigned a name
>        and these are referenced in the :term:`SRCREV_FORMAT` variable. Consider
>        an example with URLs named "machine" and "meta". In this case,

Looks good to me, thanks.

Antonin