Re: [docs][PATCH 1/5] doc: change some terminology around bitbake-setup

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

Hi,

On Mon Jan 26, 2026 at 11:27 PM CET, Daiane Angolini via lists.yoctoproject.org wrote:
> Change some terms to use more specific wording:
>
>   Generic Configuration  -> BitBake Setup Template
>   Specific Configuration -> BitBake Setup Instance


I think we agreed on naming those:

BitBake Setup Configuration Template
BitBake Setup Configuration Instance

?

Once again, I think it's important that those two terms refer to the JSON files.
I think adding "configuration" makes it clearer, especially for the "instance".

Also not sure about prefixing it with "Bitbake Setup". In your book you can
always prefix "Configuration Template/Instance" with "Bitbake Setup", but I
think in this document it clear that's it's related to bitbake-setup.

>   nested configurations  -> Variant
>
> Signed-off-by: Daiane Angolini <daiane.angolini@foundries.io>
> ---
>  .../bitbake-user-manual-environment-setup.rst | 88 +++++++++----------
>  1 file changed, 44 insertions(+), 44 deletions(-)
>
> 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 3b6a73fd8..824b01ffb 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> @@ -41,8 +41,8 @@ Quick Start
>        $ ./bitbake/bin/bitbake-setup init
>  
>     This command will ask you to choose which configurations to use available as
> -   part of the default BitBake :term:`generic configurations <generic
> -   Configuration>`.
> +   part of the default BitBake :term:`BitBake Setup Templates <BitBake Setup
> +   Template>`.
>  
>     .. note::
>  
> @@ -73,8 +73,8 @@ Quick Start
>  
>        The name of the directory will vary depending on the choices.
>  
> -   -  ``config/``: holds the :term:`Specific Configuration`, which embeds the
> -      :term:`Generic Configuration` (first choice of the :ref:`ref-bbsetup-command-init` command)
> +   -  ``config/``: holds the :term:`BitBake Setup Instance`, which embeds the
> +      :term:`BitBake Setup Template` (first choice of the :ref:`ref-bbsetup-command-init` command)
>        and the choices made during the initialization.
>  
>     -  ``build/``: the :term:`BitBake Build` directory, where BitBake stores
> @@ -145,12 +145,12 @@ The "Top Directory" and "Setup" directories are defined as follows:
>     :term:`Setup`
>        A Setup is the result of the :ref:`ref-bbsetup-command-init`
>        command, which creates a :term:`Setup` directory. It is constructed from a
> -      :term:`Generic Configuration` and choices made during the ``init`` command.
> +      :term:`BitBake Setup Template` and choices made during the ``init`` command.
>  
>        It contains at least:
>  
>        -  A :term:`BitBake Build` (``build/`` directory).
> -      -  A :term:`Specific Configuration` (``config/`` directory).
> +      -  A :term:`BitBake Setup Instance` (``config/`` directory).
>        -  Sources such as :ref:`layers
>           <bitbake-user-manual/bitbake-user-manual-intro:Layers>` or other
>           repositories managed by ``bitbake-setup`` (``layers/`` directory).
> @@ -173,8 +173,8 @@ The following components are involved to create the content of these directories
>        Build` constitute the :ref:`BitBake configuration
>        <bitbake-user-manual/bitbake-user-manual-intro:Configuration Files>`.
>  
> -   :term:`Generic Configuration`
> -      A Generic Configuration is a file in JSON format containing a template to
> +   :term:`BitBake Setup Template`
> +      A BitBake Setup Template is a file in JSON format containing a template to
>        create a :term:`Setup`. These files are used during the :ref:`ref-bbsetup-command-init`
>        command as a starting point to configure the :term:`Setup`. When the
>        command runs, the user may be prompted with choices to further specify the
> @@ -183,42 +183,42 @@ The following components are involved to create the content of these directories
>        It is also possible to specify the choices on the command line for a
>        completely non-interactive initialization.
>  
> -      :term:`Generic Configuration` files are stored in :term:`registries
> +      :term:`BitBake Setup Template` files are stored in :term:`registries
>        <Registry>`, and can be listed with the :ref:`ref-bbsetup-command-list`
>        command.
>  
> -      :term:`Generic Configuration` files must end with the ``.conf.json``
> +      :term:`BitBake Setup Template` files must end with the ``.conf.json``
>        suffix for ``bitbake-setup`` to locate them.
>  
>        .. note::
>  
> -         The default :term:`Generic Configurations <Generic Configuration>` are
> +         The default :term:`BitBake Setup Templates <BitBake Setup Template>` are
>           located in the BitBake repository in a local registry. the
>           ``default-registry/`` directory. This can be modified with the
>           :ref:`ref-bbsetup-setting-registry` setting.
>  
>        :ref:`ref-bbsetup-command-status` will tell if a :term:`Setup`
> -      is in sync with the :term:`Generic Configuration` it was constructed from
> +      is in sync with the :term:`BitBake Setup Template` it was constructed from
>        (typically: layer updates).
>  
>        :ref:`ref-bbsetup-command-update` will bring a :term:`Setup`
> -      in sync with its :term:`Generic Configuration`.
> +      in sync with its :term:`BitBake Setup Template`.
>  
> -   :term:`Specific Configuration`
> -      The :term:`Specific Configuration` is stored in the ``config/`` directory
> -      in a :term:`Setup`. It embeds the :term:`Generic Configuration` and the
> +   :term:`BitBake Setup Instance`
> +      The :term:`BitBake Setup Instance` is stored in the ``config/`` directory
> +      in a :term:`Setup`. It embeds the :term:`BitBake Setup Template` and the
>        choices made during the initialization.
>  
> -      It is also a Git repository, that contains a history of the specific
> -      configuration and updates made to it via :ref:`ref-bbsetup-command-update`.
> +      It is also a Git repository, that contains a history of the setup instance
> +      and updates made to it via :ref:`ref-bbsetup-command-update`.
>  
>     :term:`Registry`
> -      A configuration registry is a place where one or more :term:`Generic
> -      Configurations <Generic Configuration>` are stored.
> +      A configuration registry is a place where one or more :term:`BitBake
> +      Setup Templates <BitBake Setup Template>` are stored.
>  
>        The directory structure of the registry can be any: ``bitbake-setup``
>        recursively find files ending with ``.conf.json`` and consider it a
> -      :term:`Generic Configuration`.
> +      :term:`BitBake Setup Template`.
>  
>        The registry location is configured through the
>        :ref:`ref-bbsetup-setting-registry` setting. This location can be the URL to
> @@ -279,7 +279,7 @@ The ``bitbake-setup init`` sub-command helps initializing a :term:`Setup`.
>  
>  This command can be run without any arguments to prompt the user with
>  configuration options to choose from. These configuration options are taken from
> -the input :term:`Generic Configuration` files in the :term:`registry`.
> +the input :term:`BitBake Setup Template` files in the :term:`registry`.
>  
>  .. note::
>  
> @@ -288,9 +288,9 @@ the input :term:`Generic Configuration` files in the :term:`registry`.
>  
>  Otherwise, the first argument to :ref:`ref-bbsetup-command-init` can be:
>  
> --  A generic configuration ID in the registry.
> --  A path to a generic configuration file on a local disk.
> --  An HTTP URI to the generic configuration file.
> +-  A BitBake Setup Template ID in the registry.
> +-  A path to a BitBake Setup Template file on a local disk.
> +-  An HTTP URI to the BitBake Setup Template file.
>  
>  The choices made during the bare ``bitbake-setup init`` command can also be
>  passed directly on the command-line, for example::
> @@ -331,7 +331,7 @@ In addition, the command can take the following arguments:
>  ``bitbake-setup init`` Examples
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  
> --  This example prompts the user to choose a :term:`Generic Configuration` from
> +-  This example prompts the user to choose a :term:`BitBake Setup Template` from
>     a custom registry:
>  
>     .. code-block:: shell
> @@ -340,7 +340,7 @@ In addition, the command can take the following arguments:
>            --setting default registry 'git://example.com/bitbake-setup-configurations.git;protocol=https;branch=main;rev=main' \
>            init
>  
> --  This example takes a :term:`Generic Configuration` from a remote location
> +-  This example takes a :term:`BitBake Setup Template` from a remote location
>     (here, one of the default configuration in BitBake):
>  
>     .. code-block:: shell
> @@ -351,7 +351,7 @@ In addition, the command can take the following arguments:
>  
>     -  A custom :ref:`ref-bbsetup-setting-top-dir-prefix` and :ref:`ref-bbsetup-setting-top-dir-name`
>     -  A :term:`source override`, and additionally overriding openembedded-core with a locally managed directory.
> -   -  A standalone :term:`generic configuration` file.
> +   -  A standalone :term:`BitBake Setup Template` file.
>     -  Choices passed on the command-line, applied non-interactively.
>  
>     .. code-block:: shell
> @@ -371,8 +371,8 @@ In addition, the command can take the following arguments:
>  ``bitbake-setup list``
>  ----------------------
>  
> -The ``bitbake-setup list`` sub-command lists the available :term:`generic
> -configurations <generic configuration>` in the current :term:`registry`.
> +The ``bitbake-setup list`` sub-command lists the available :term:`BitBake Setup
> +Templates <BitBake Setup Template>` in the current :term:`registry`.
>  
>  In addition, the command can take the following arguments:
>  
> @@ -388,8 +388,8 @@ In addition, the command can take the following arguments:
>  ------------------------
>  
>  The ``bitbake-setup status`` sub-command shows the status of a
> -:term:`Setup`. Any differences between the local copy of the :term:`generic
> -configuration` and the upstream one are printed on the console.
> +:term:`Setup`. Any differences between the local copy of the :term:`BitBake Setup
> +Template` and the upstream one are printed on the console.
>  
>  If the BitBake environment is sourced and ready to build, the ``bitbake-setup
>  status`` command (without any arguments) will show the status of the current
> @@ -407,7 +407,7 @@ In addition, the command can take the following arguments:
>  ------------------------
>  
>  The ``bitbake-setup update`` sub-command updates a :term:`Setup` to sync with
> -the latest changes from a :term:`generic configuration` it was constructed from.
> +the latest changes from the :term:`BitBake Setup Template` it was constructed from.
>  The :ref:`ref-bbsetup-command-status` command can be used to show the current
>  status of the :term:`Setup` before updating it.
>  
> @@ -617,16 +617,16 @@ manner.
>  
>  The :ref:`ref-bbsetup-setting-use-full-setup-dir-name` setting, if set to ``yes``
>  will override the suggestions for the :term:`Setup` directory name made by
> -``setup-dir-name`` entries in :term:`Generic Configuration` files. This
> +``setup-dir-name`` entries in :term:`BitBake Setup Template` files. This
>  will make the directory names longer, but fully specific: they will contain
>  all selections made during initialization.
>  
>  .. _ref-bbsetup-section-config-reference:
>  
> -Generic Configuration Files Reference
> -=====================================
> +BitBake Setup Template Files Reference
> +======================================

I think this is missing some modifications below?

e.g:

"""
-  ``bitbake-setup`` (**required**): contains a list of configurations.
"""

can be turned into

"""
-  ``bitbake-setup`` (**required**): contains a list of :term:`Variants
   <Variant>`.
"""

Antonin

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