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

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

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

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