[1/5] doc: document fixed revisions override in bitbake-setup manual

From: Alexander Kanavin <alex@linutronix.de>

Signed-off-by: Alexander Kanavin <alex@linutronix.de>
---
 .../bitbake-user-manual-environment-setup.rst | 48 +++++++++++++++++++
 1 file changed, 48 insertions(+)

Hi Alex,

On 1/9/26 2:19 PM, Alexander Kanavin via lists.openembedded.org wrote:
> From: Alexander Kanavin <alex@linutronix.de>
> 
> Signed-off-by: Alexander Kanavin <alex@linutronix.de>
> ---
>   .../bitbake-user-manual-environment-setup.rst | 48 +++++++++++++++++++
>   1 file changed, 48 insertions(+)
> 
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> index ec1bdeecd..fcffab812 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> @@ -938,3 +938,51 @@ Here is an example file that overrides the branch of the BitBake repository to
>   -  The ``sources`` section contains the same options as the ``sources`` option
>      of a :term:`Generic Configuration` file. See the
>      :ref:`ref-bbsetup-section-config-reference` section for more information.
> +
> +.. _ref-bbsetup-fixed-revisions:
> +

We have autosectionlabel sphinx extension enabled, so this shouldn't be 
necessary. I know Antonin's got some opinion on when to use manual 
labels vs autolabels so up to him to decide. Would be nice to have some 
sort of rule documented somewhere :)

> +Fixed source revisions
> +======================
> +
> +:term:`Generic Configuration` can set source revisions in ``rev`` to a tag or a branch.

Will the tag be refetched every time or once it's available locally, if 
the tag is moved upstream it's not changed locally?

> +Bitbake-setup will make sure the actual revision will match the tag or branch when performing

Do not capitalize bitbake-setup, it is a tool that is named like that. 
Maybe highlight it as such as well:

``bitbake-setup``

> +initializations or updates, and will capture the revisions in a :ref:`_ref-bbsetup-source-overrides`
> +file.> +
> +This file is named ``sources-fixed-revisions.json`` and is available in ``layers/``
> +under the :term:`Setup` directory (as well as under ``config/`` for backwards compatibility).
> +It can be used to keep record of what was checked out when using configurations that do not
> +specify exact revisions.
> +
> +Also, as it is an override file, it can be combined with the original configurations
> +to initialize a setup in a reproducible way that guarantees an exact, never-changing
> +set of revisions, by using the ``--source-overrides`` option of the
> +:ref:`ref-bbsetup-command-init` command.
> +
> +For example if the original configuration had specified only a master branch
> +for a source::
> +

This is JSON I believe? So probably:

.. code-block:: json

instead?

> +     "bitbake": {
> +         "git-remote": {
> +             "remotes": {
> +                 "origin": {
> +                     "uri": "https://git.openembedded.org/bitbake"
> +                 }
> +             },
> +             "branch": "master",
> +             "rev": "master"
> +     }
> +
> +
> +the override will contain the exact revisions::
> +

Ditto.

Cheers,
Quentin

On Thu, 15 Jan 2026 at 12:50, Quentin Schulz <quentin.schulz@cherry.de> wrote:
> > +Fixed source revisions
> > +======================
> > +
> > +:term:`Generic Configuration` can set source revisions in ``rev`` to a tag or a branch.
>
> Will the tag be refetched every time or once it's available locally, if
> the tag is moved upstream it's not changed locally?

I have not verified that, and there's no specific test for it, but I
think tags will be refetched, same way as branch references will also
be refetched if there are new commits in them (for that there is a
test).

This patch has already merged, so if you can do the fixups in a
followup I'd appreciate (you can probably go over the entire document
and check for consistency).

Alex

Hi,

On Thu Jan 15, 2026 at 12:50 PM CET, Quentin Schulz via lists.openembedded.org wrote:
> Hi Alex,
>
> On 1/9/26 2:19 PM, Alexander Kanavin via lists.openembedded.org wrote:
>> From: Alexander Kanavin <alex@linutronix.de>
>> 
>> Signed-off-by: Alexander Kanavin <alex@linutronix.de>
>> ---
>>   .../bitbake-user-manual-environment-setup.rst | 48 +++++++++++++++++++
>>   1 file changed, 48 insertions(+)
>> 
>> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
>> index ec1bdeecd..fcffab812 100644
>> --- a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
>> +++ b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
>> @@ -938,3 +938,51 @@ Here is an example file that overrides the branch of the BitBake repository to
>>   -  The ``sources`` section contains the same options as the ``sources`` option
>>      of a :term:`Generic Configuration` file. See the
>>      :ref:`ref-bbsetup-section-config-reference` section for more information.
>> +
>> +.. _ref-bbsetup-fixed-revisions:
>> +
>
> We have autosectionlabel sphinx extension enabled, so this shouldn't be 
> necessary. I know Antonin's got some opinion on when to use manual 
> labels vs autolabels so up to him to decide. Would be nice to have some 
> sort of rule documented somewhere :)

I don't think having a custom ref prevents from using autosectionlabels, so I'm
fine either way.

[...]
>> +
>> +Also, as it is an override file, it can be combined with the original configurations
>> +to initialize a setup in a reproducible way that guarantees an exact, never-changing
>> +set of revisions, by using the ``--source-overrides`` option of the
>> +:ref:`ref-bbsetup-command-init` command.
>> +
>> +For example if the original configuration had specified only a master branch
>> +for a source::
>> +
>
> This is JSON I believe? So probably:
>
> .. code-block:: json

Careful with that I think Sphinx is not happy when the underlying JSON is not
valid JSON (missing comma or unmatched curly braces etc.)

Antonin