[09/10] 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 | 46 +++++++++++++++++++
 1 file changed, 46 insertions(+)

Hi,

On Fri Jan 2, 2026 at 8:34 PM CET, 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 | 46 +++++++++++++++++++
>  1 file changed, 46 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..68b2ad31d 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,49 @@ 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

Missing colon at the end:

.. _ref-bbsetup-fixed-revisions:

otherwise this is treated as a comment.

> +
> +Fixed source revisions
> +======================
> +
> +:term:`Generic Configuration` can set source revisions in ``rev`` to a tag or a branch.
> +Bitbake-setup will make sure the actual revision will match the tag or branch when performing
> +initializations or updates, and will capture the revisions in a :ref:`_ref-bbsetup-source-overrides`
> +file.
> +
> +The file is named ``sources-fixed-revisions.json`` and is available in ``layers/``

s/The/This/ ?

if this is a continuation to your previous sentence

> +or ``config/`` under :term:`Setup` directory. It can be used to keep record of

s/under :term:`Setup` directory/under the :term:`Setup` directory/

Why layers/ _or_ config/? It's ambiguous for users reading here what the
difference between the two might be. If this is a compatibility thing (because
bitbake-setup used to do it one way, then it was changed to another location), I
would just keep the final one documented here (or explain that it's for
compatibility).

> +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.
> +
> +For example if the original configuration had specified only a master branch
> +for a source::
> +
> +     "bitbake": {
> +         "git-remote": {
> +             "remotes": {
> +                 "origin": {
> +                     "uri": "https://git.openembedded.org/bitbake"
> +                 }
> +             },
> +             "branch": "master",
> +             "rev": "master"
> +     }
> +
> +
> +the override will contain the exact revisions::
> +
> +     "bitbake": {
> +         "git-remote": {
> +             "remotes": {
> +                 "origin": {
> +                     "uri": "https://git.openembedded.org/bitbake"
> +                 }
> +             },
> +             "branch": "master",
> +             "rev": "720df1a53452983c1c832f624490e255cf389204"
> +     }

"""
This file can later be used with the ``--source-overrides`` option of the
:ref:`ref-bbsetup-command-init` command.
"""

?

Thanks,
Antonin

Thanks, I corrected all of these and sent a v2.

Alex

On Tue, 6 Jan 2026 at 09:52, Antonin Godard <antonin.godard@bootlin.com> wrote:
>
> Hi,
>
> On Fri Jan 2, 2026 at 8:34 PM CET, 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 | 46 +++++++++++++++++++
> >  1 file changed, 46 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..68b2ad31d 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,49 @@ 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
>
> Missing colon at the end:
>
> .. _ref-bbsetup-fixed-revisions:
>
> otherwise this is treated as a comment.
>
> > +
> > +Fixed source revisions
> > +======================
> > +
> > +:term:`Generic Configuration` can set source revisions in ``rev`` to a tag or a branch.
> > +Bitbake-setup will make sure the actual revision will match the tag or branch when performing
> > +initializations or updates, and will capture the revisions in a :ref:`_ref-bbsetup-source-overrides`
> > +file.
> > +
> > +The file is named ``sources-fixed-revisions.json`` and is available in ``layers/``
>
> s/The/This/ ?
>
> if this is a continuation to your previous sentence
>
> > +or ``config/`` under :term:`Setup` directory. It can be used to keep record of
>
> s/under :term:`Setup` directory/under the :term:`Setup` directory/
>
> Why layers/ _or_ config/? It's ambiguous for users reading here what the
> difference between the two might be. If this is a compatibility thing (because
> bitbake-setup used to do it one way, then it was changed to another location), I
> would just keep the final one documented here (or explain that it's for
> compatibility).
>
> > +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.
> > +
> > +For example if the original configuration had specified only a master branch
> > +for a source::
> > +
> > +     "bitbake": {
> > +         "git-remote": {
> > +             "remotes": {
> > +                 "origin": {
> > +                     "uri": "https://git.openembedded.org/bitbake"
> > +                 }
> > +             },
> > +             "branch": "master",
> > +             "rev": "master"
> > +     }
> > +
> > +
> > +the override will contain the exact revisions::
> > +
> > +     "bitbake": {
> > +         "git-remote": {
> > +             "remotes": {
> > +                 "origin": {
> > +                     "uri": "https://git.openembedded.org/bitbake"
> > +                 }
> > +             },
> > +             "branch": "master",
> > +             "rev": "720df1a53452983c1c832f624490e255cf389204"
> > +     }
>
> """
> This file can later be used with the ``--source-overrides`` option of the
> :ref:`ref-bbsetup-command-init` command.
> """
>
> ?
>
> Thanks,
> Antonin
>
> --
> Antonin Godard, Bootlin
> Embedded Linux and Kernel engineering
> https://bootlin.com
>