[PATCH 0/2] bitbake-setup docs fixes

[PATCH 0/2] bitbake-setup docs fixes

[Antonin Godard]

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
Antonin Godard (2):
      bitbake-setup: rename "abort" rebase conflict stragegy to "halt"
      doc/bitbake-user-manual-environment-setup.rst: replace shell blocks by console

 bin/bitbake-setup                                  |  8 ++---
 .../bitbake-user-manual-environment-setup.rst      | 36 +++++++++++-----------
 .../bitbake-user-manual-fetching.rst               |  2 +-
 lib/bb/tests/setup.py                              |  8 ++---
 4 files changed, 27 insertions(+), 27 deletions(-)
---
base-commit: 7cf11787ee7942a00ba7e8fa2c590a2563070c38
change-id: 20260331-docs-fixes-0dcb4e95b16f

[PATCH 1/2] bitbake-setup: rename "abort" rebase conflict stragegy to "halt"

[Antonin Godard]

As per [1], do not use the word "abort" and replace it with "halt" for
the rebase conflicts strategy. This is something we try to follow in our
documentation.

[1]: https://inclusivenaming.org/word-lists/tier-1/abort/

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 bin/bitbake-setup                                                 | 8 ++++----
 doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst | 6 +++---
 doc/bitbake-user-manual/bitbake-user-manual-fetching.rst          | 2 +-
 lib/bb/tests/setup.py                                             | 8 ++++----
 4 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/bin/bitbake-setup b/bin/bitbake-setup
index b02cbc2b1c4..33cbefb4914 100755
--- a/bin/bitbake-setup
+++ b/bin/bitbake-setup
@@ -167,7 +167,7 @@ def _get_remotes(r_remote):
 
     return remotes
 
-def checkout_layers(layers, confdir, layerdir, d, rebase_conflicts_strategy='abort'):
+def checkout_layers(layers, confdir, layerdir, d, rebase_conflicts_strategy='halt'):
     def _checkout_git_remote(r_remote, repodir, layers_fixed_revisions):
         rev = r_remote['rev']
         branch = r_remote.get('branch', None)
@@ -458,7 +458,7 @@ def merge_overrides_into_sources(sources, overrides):
             layers[k] = v
     return layers
 
-def update_build(config, confdir, setupdir, layerdir, d, update_bb_conf="prompt", init_vscode=False, rebase_conflicts_strategy='abort'):
+def update_build(config, confdir, setupdir, layerdir, d, update_bb_conf="prompt", init_vscode=False, rebase_conflicts_strategy='halt'):
     layer_config = merge_overrides_into_sources(config["data"]["sources"], config["source-overrides"]["sources"])
     sources_fixed_revisions = checkout_layers(layer_config, confdir, layerdir, d, rebase_conflicts_strategy=rebase_conflicts_strategy)
     bitbake_config = config["bitbake-config"]
@@ -1273,9 +1273,9 @@ def main():
     parser_update = subparsers.add_parser('update', help='Update a setup to be in sync with configuration')
     add_setup_dir_arg(parser_update)
     parser_update.add_argument('--update-bb-conf', choices=['prompt', 'yes', 'no'], default='prompt', help='Update bitbake configuration files (bblayers.conf, local.conf) (default: prompt)')
-    parser_update.add_argument('--rebase-conflicts-strategy', choices=['abort', 'backup'], default='abort',
+    parser_update.add_argument('--rebase-conflicts-strategy', choices=['halt', 'backup'], default='halt',
                         help="What to do when a layer repository has local modifications that prevent "
-                             "an in-place update: 'abort' (default) aborts with an error message; "
+                             "an in-place update: 'halt' (default) halts with an error message; "
                              "'backup' renames the directory to a timestamped backup and re-clones from upstream.")
     parser_update.set_defaults(func=build_update)
 
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 c22e19bd665..c7b73001404 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
@@ -458,9 +458,9 @@ In addition, the command can take the following arguments:
    local modifications or commits that prevent an in-place update. Accepted
    values are:
 
-   -  ``abort`` (default): stop with an error message describing the problem.
+   -  ``halt`` (default): stop with an error message describing the problem.
       The repository is left in its previous state (the failed rebase is
-      automatically aborted). The error message includes a hint to re-run with
+      automatically halted). The error message includes a hint to re-run with
       ``--rebase-conflicts-strategy=backup``.
    -  ``backup``: rename the conflicting layer directory to a timestamped
       ``<name>-backup-<timestamp>`` path (preserving local work), then
@@ -523,7 +523,7 @@ In addition, the command can take the following arguments:
 
 -  This example shows what happens when a layer directory contains local
    commits that conflict with the incoming upstream changes. The failed rebase
-   is automatically aborted, and the ``dldir`` remote is left in the repository
+   is automatically halted, and the ``dldir`` remote is left in the repository
    for manual resolution:
 
    .. code-block:: shell
diff --git a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
index c2747c40124..fbfc9600f12 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
@@ -223,7 +223,7 @@ The method raises an error if:
 -  The working tree contains staged or unstaged changes to tracked
    files (``LocalModificationsError``).
 -  Local commits cannot be cleanly rebased onto the new upstream
-   revision (``RebaseError``). A failed rebase is automatically aborted
+   revision (``RebaseError``). A failed rebase is automatically halted
    before the exception is raised.
 -  The download cache does not contain a sufficiently recent clone
    of the repository, or the checkout is a shallow clone.
diff --git a/lib/bb/tests/setup.py b/lib/bb/tests/setup.py
index 638d56d3bb3..c85013eb4d4 100644
--- a/lib/bb/tests/setup.py
+++ b/lib/bb/tests/setup.py
@@ -639,14 +639,14 @@ print("BBPATH is {{}}".format(os.environ["BBPATH"]))
         """Test the --rebase-conflicts-strategy option for the update command.
 
         Covers three scenarios not exercised by test_setup:
-        1. Uncommitted tracked-file change (LocalModificationsError) + default 'abort'
+        1. Uncommitted tracked-file change (LocalModificationsError) + default 'halt'
            strategy → clean error message containing 'has uncommitted changes' and a
            hint at --rebase-conflicts-strategy=backup; no backup directory is created.
         2. Same uncommitted change + 'backup' strategy → directory is renamed to a
            timestamped backup and the layer is re-cloned cleanly.
         3. Committed local change that conflicts with an incoming upstream commit
            (RebaseError):
-           a. Default 'abort' strategy → error containing 'Merge conflict' and the
+           a. Default 'halt' strategy → error containing 'Merge conflict' and the
               --rebase-conflicts-strategy=backup hint; no backup directory is created.
            b. 'backup' strategy → backup + re-clone instead of a hard failure.
         """
@@ -663,7 +663,7 @@ print("BBPATH is {{}}".format(os.environ["BBPATH"]))
         layer_path = os.path.join(setuppath, 'layers', 'test-repo')
         layers_path = os.path.join(setuppath, 'layers')
 
-        # Scenario 1: uncommitted tracked change, default 'abort' strategy
+        # Scenario 1: uncommitted tracked change, default 'halt' strategy
         # Advance upstream so an update is required.
         self.add_file_to_testrepo('test-file', 'upstream-v2\n')
         # Modify the same tracked file in the layer without committing.
@@ -677,7 +677,7 @@ print("BBPATH is {{}}".format(os.environ["BBPATH"]))
         self.assertIn('--rebase-conflicts-strategy=backup', str(ctx.exception))
         # No backup directory must have been created.
         self.assertEqual(self._count_layer_backups(layers_path), 0,
-                         "abort strategy must not create any backup")
+                         "halt strategy must not create any backup")
 
         # Scenario 2: same uncommitted change, 'backup' strategy
         out = self.runbbsetup("update --update-bb-conf='no' --rebase-conflicts-strategy=backup")

-- 
2.53.0

Re: [docs] [PATCH 1/2] bitbake-setup: rename "abort" rebase conflict stragegy to "halt"

[Quentin Schulz]

Hi Antonin,

On 3/31/26 10:14 AM, Antonin Godard via lists.yoctoproject.org wrote:
> As per [1], do not use the word "abort" and replace it with "halt" for
> the rebase conflicts strategy. This is something we try to follow in our
> documentation.
> 
> [1]: https://inclusivenaming.org/word-lists/tier-1/abort/
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   bin/bitbake-setup                                                 | 8 ++++----
>   doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst | 6 +++---
>   doc/bitbake-user-manual/bitbake-user-manual-fetching.rst          | 2 +-
>   lib/bb/tests/setup.py                                             | 8 ++++----
>   4 files changed, 12 insertions(+), 12 deletions(-)
> 
> diff --git a/bin/bitbake-setup b/bin/bitbake-setup
> index b02cbc2b1c4..33cbefb4914 100755
> --- a/bin/bitbake-setup
> +++ b/bin/bitbake-setup
> @@ -167,7 +167,7 @@ def _get_remotes(r_remote):
>   
>       return remotes
>   
> -def checkout_layers(layers, confdir, layerdir, d, rebase_conflicts_strategy='abort'):
> +def checkout_layers(layers, confdir, layerdir, d, rebase_conflicts_strategy='halt'):
>       def _checkout_git_remote(r_remote, repodir, layers_fixed_revisions):
>           rev = r_remote['rev']
>           branch = r_remote.get('branch', None)
> @@ -458,7 +458,7 @@ def merge_overrides_into_sources(sources, overrides):
>               layers[k] = v
>       return layers
>   
> -def update_build(config, confdir, setupdir, layerdir, d, update_bb_conf="prompt", init_vscode=False, rebase_conflicts_strategy='abort'):
> +def update_build(config, confdir, setupdir, layerdir, d, update_bb_conf="prompt", init_vscode=False, rebase_conflicts_strategy='halt'):
>       layer_config = merge_overrides_into_sources(config["data"]["sources"], config["source-overrides"]["sources"])
>       sources_fixed_revisions = checkout_layers(layer_config, confdir, layerdir, d, rebase_conflicts_strategy=rebase_conflicts_strategy)
>       bitbake_config = config["bitbake-config"]
> @@ -1273,9 +1273,9 @@ def main():
>       parser_update = subparsers.add_parser('update', help='Update a setup to be in sync with configuration')
>       add_setup_dir_arg(parser_update)
>       parser_update.add_argument('--update-bb-conf', choices=['prompt', 'yes', 'no'], default='prompt', help='Update bitbake configuration files (bblayers.conf, local.conf) (default: prompt)')
> -    parser_update.add_argument('--rebase-conflicts-strategy', choices=['abort', 'backup'], default='abort',
> +    parser_update.add_argument('--rebase-conflicts-strategy', choices=['halt', 'backup'], default='halt',
>                           help="What to do when a layer repository has local modifications that prevent "
> -                             "an in-place update: 'abort' (default) aborts with an error message; "
> +                             "an in-place update: 'halt' (default) halts with an error message; "
>                                "'backup' renames the directory to a timestamped backup and re-clones from upstream.")
>       parser_update.set_defaults(func=build_update)
>   
> 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 c22e19bd665..c7b73001404 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> @@ -458,9 +458,9 @@ In addition, the command can take the following arguments:
>      local modifications or commits that prevent an in-place update. Accepted
>      values are:
>   
> -   -  ``abort`` (default): stop with an error message describing the problem.
> +   -  ``halt`` (default): stop with an error message describing the problem.
>         The repository is left in its previous state (the failed rebase is
> -      automatically aborted). The error message includes a hint to re-run with
> +      automatically halted). The error message includes a hint to re-run with

This is not what halt means. Maybe 'reset' would be a better choice? Or 
if you really want to follow the recommendations from that website, I 
guess "cancel"?

Cheers,
Quentin

Re: [docs] [PATCH 1/2] bitbake-setup: rename "abort" rebase conflict stragegy to "halt"

[Richard Purdie]

On Tue, 2026-03-31 at 11:00 +0200, Quentin Schulz via lists.yoctoproject.org wrote:
> Hi Antonin,
> 
> On 3/31/26 10:14 AM, Antonin Godard via lists.yoctoproject.org wrote:
> > As per [1], do not use the word "abort" and replace it with "halt" for
> > the rebase conflicts strategy. This is something we try to follow in our
> > documentation.
> > 
> > [1]: https://inclusivenaming.org/word-lists/tier-1/abort/
> > 
> > Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> > ---
> >   bin/bitbake-setup                                                 | 8 ++++----
> >   doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst | 6 +++---
> >   doc/bitbake-user-manual/bitbake-user-manual-fetching.rst          | 2 +-
> >   lib/bb/tests/setup.py                                             | 8 ++++----
> >   4 files changed, 12 insertions(+), 12 deletions(-)
> > 
> > diff --git a/bin/bitbake-setup b/bin/bitbake-setup
> > index b02cbc2b1c4..33cbefb4914 100755
> > --- a/bin/bitbake-setup
> > +++ b/bin/bitbake-setup
> > @@ -167,7 +167,7 @@ def _get_remotes(r_remote):
> >   
> >       return remotes
> >   
> > -def checkout_layers(layers, confdir, layerdir, d, rebase_conflicts_strategy='abort'):
> > +def checkout_layers(layers, confdir, layerdir, d, rebase_conflicts_strategy='halt'):
> >       def _checkout_git_remote(r_remote, repodir, layers_fixed_revisions):
> >           rev = r_remote['rev']
> >           branch = r_remote.get('branch', None)
> > @@ -458,7 +458,7 @@ def merge_overrides_into_sources(sources, overrides):
> >               layers[k] = v
> >       return layers
> >   
> > -def update_build(config, confdir, setupdir, layerdir, d, update_bb_conf="prompt", init_vscode=False, rebase_conflicts_strategy='abort'):
> > +def update_build(config, confdir, setupdir, layerdir, d, update_bb_conf="prompt", init_vscode=False, rebase_conflicts_strategy='halt'):
> >       layer_config = merge_overrides_into_sources(config["data"]["sources"], config["source-overrides"]["sources"])
> >       sources_fixed_revisions = checkout_layers(layer_config, confdir, layerdir, d, rebase_conflicts_strategy=rebase_conflicts_strategy)
> >       bitbake_config = config["bitbake-config"]
> > @@ -1273,9 +1273,9 @@ def main():
> >       parser_update = subparsers.add_parser('update', help='Update a setup to be in sync with configuration')
> >       add_setup_dir_arg(parser_update)
> >       parser_update.add_argument('--update-bb-conf', choices=['prompt', 'yes', 'no'], default='prompt', help='Update bitbake configuration files (bblayers.conf, local.conf) (default: prompt)')
> > -    parser_update.add_argument('--rebase-conflicts-strategy', choices=['abort', 'backup'], default='abort',
> > +    parser_update.add_argument('--rebase-conflicts-strategy', choices=['halt', 'backup'], default='halt',
> >                           help="What to do when a layer repository has local modifications that prevent "
> > -                             "an in-place update: 'abort' (default) aborts with an error message; "
> > +                             "an in-place update: 'halt' (default) halts with an error message; "
> >                                "'backup' renames the directory to a timestamped backup and re-clones from upstream.")
> >       parser_update.set_defaults(func=build_update)
> >   
> > 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 c22e19bd665..c7b73001404 100644
> > --- a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> > +++ b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> > @@ -458,9 +458,9 @@ In addition, the command can take the following arguments:
> >      local modifications or commits that prevent an in-place update. Accepted
> >      values are:
> >   
> > -   -  ``abort`` (default): stop with an error message describing the problem.
> > +   -  ``halt`` (default): stop with an error message describing the problem.
> >         The repository is left in its previous state (the failed rebase is
> > -      automatically aborted). The error message includes a hint to re-run with
> > +      automatically halted). The error message includes a hint to re-run with
> 
> This is not what halt means. Maybe 'reset' would be a better choice? Or 
> if you really want to follow the recommendations from that website, I
> guess "cancel"?

The trouble is none of these alternatives really match what abort
means, reset and cancel do mean something different. "abandon" might be
closer but still isn't right. "attempt" maybe? If we get too creative
with this, users just won't understand what it means :(

Cheers,

Richard

Re: [bitbake-devel] [docs] [PATCH 1/2] bitbake-setup: rename "abort" rebase conflict stragegy to "halt"

[Alexander Kanavin]

[-- Attachment #1: Type: text/plain, Size: 5842 bytes --]

There’s a simpler rationale too: this follows ‘git rebase —abort’. If git
upstream finds a better word, we will follow. And I agree that all of the
proposed alternatives are less accurate.

Alex

On Tue 31. Mar 2026 at 12.43, Richard Purdie via lists.openembedded.org
<richard.purdie=linuxfoundation.org@lists.openembedded.org> wrote:

> On Tue, 2026-03-31 at 11:00 +0200, Quentin Schulz via
> lists.yoctoproject.org wrote:
> > Hi Antonin,
> >
> > On 3/31/26 10:14 AM, Antonin Godard via lists.yoctoproject.org wrote:
> > > As per [1], do not use the word "abort" and replace it with "halt" for
> > > the rebase conflicts strategy. This is something we try to follow in
> our
> > > documentation.
> > >
> > > [1]: https://inclusivenaming.org/word-lists/tier-1/abort/
> > >
> > > Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> > > ---
> > >   bin/bitbake-setup                                                 |
> 8 ++++----
> > >   doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst |
> 6 +++---
> > >   doc/bitbake-user-manual/bitbake-user-manual-fetching.rst          |
> 2 +-
> > >   lib/bb/tests/setup.py                                             |
> 8 ++++----
> > >   4 files changed, 12 insertions(+), 12 deletions(-)
> > >
> > > diff --git a/bin/bitbake-setup b/bin/bitbake-setup
> > > index b02cbc2b1c4..33cbefb4914 100755
> > > --- a/bin/bitbake-setup
> > > +++ b/bin/bitbake-setup
> > > @@ -167,7 +167,7 @@ def _get_remotes(r_remote):
> > >
> > >       return remotes
> > >
> > > -def checkout_layers(layers, confdir, layerdir, d,
> rebase_conflicts_strategy='abort'):
> > > +def checkout_layers(layers, confdir, layerdir, d,
> rebase_conflicts_strategy='halt'):
> > >       def _checkout_git_remote(r_remote, repodir,
> layers_fixed_revisions):
> > >           rev = r_remote['rev']
> > >           branch = r_remote.get('branch', None)
> > > @@ -458,7 +458,7 @@ def merge_overrides_into_sources(sources,
> overrides):
> > >               layers[k] = v
> > >       return layers
> > >
> > > -def update_build(config, confdir, setupdir, layerdir, d,
> update_bb_conf="prompt", init_vscode=False,
> rebase_conflicts_strategy='abort'):
> > > +def update_build(config, confdir, setupdir, layerdir, d,
> update_bb_conf="prompt", init_vscode=False,
> rebase_conflicts_strategy='halt'):
> > >       layer_config =
> merge_overrides_into_sources(config["data"]["sources"],
> config["source-overrides"]["sources"])
> > >       sources_fixed_revisions = checkout_layers(layer_config, confdir,
> layerdir, d, rebase_conflicts_strategy=rebase_conflicts_strategy)
> > >       bitbake_config = config["bitbake-config"]
> > > @@ -1273,9 +1273,9 @@ def main():
> > >       parser_update = subparsers.add_parser('update', help='Update a
> setup to be in sync with configuration')
> > >       add_setup_dir_arg(parser_update)
> > >       parser_update.add_argument('--update-bb-conf',
> choices=['prompt', 'yes', 'no'], default='prompt', help='Update bitbake
> configuration files (bblayers.conf, local.conf) (default: prompt)')
> > > -    parser_update.add_argument('--rebase-conflicts-strategy',
> choices=['abort', 'backup'], default='abort',
> > > +    parser_update.add_argument('--rebase-conflicts-strategy',
> choices=['halt', 'backup'], default='halt',
> > >                           help="What to do when a layer repository has
> local modifications that prevent "
> > > -                             "an in-place update: 'abort' (default)
> aborts with an error message; "
> > > +                             "an in-place update: 'halt' (default)
> halts with an error message; "
> > >                                "'backup' renames the directory to a
> timestamped backup and re-clones from upstream.")
> > >       parser_update.set_defaults(func=build_update)
> > >
> > > 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 c22e19bd665..c7b73001404 100644
> > > --- a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> > > +++ b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
> > > @@ -458,9 +458,9 @@ In addition, the command can take the following
> arguments:
> > >      local modifications or commits that prevent an in-place update.
> Accepted
> > >      values are:
> > >
> > > -   -  ``abort`` (default): stop with an error message describing the
> problem.
> > > +   -  ``halt`` (default): stop with an error message describing the
> problem.
> > >         The repository is left in its previous state (the failed
> rebase is
> > > -      automatically aborted). The error message includes a hint to
> re-run with
> > > +      automatically halted). The error message includes a hint to
> re-run with
> >
> > This is not what halt means. Maybe 'reset' would be a better choice? Or
> > if you really want to follow the recommendations from that website, I
> > guess "cancel"?
>
> The trouble is none of these alternatives really match what abort
> means, reset and cancel do mean something different. "abandon" might be
> closer but still isn't right. "attempt" maybe? If we get too creative
> with this, users just won't understand what it means :(
>
> Cheers,
>
> Richard
>
>
> -=-=-=-=-=-=-=-=-=-=-=-
> Links: You receive all messages sent to this group.
> View/Reply Online (#19290):
> https://lists.openembedded.org/g/bitbake-devel/message/19290
> Mute This Topic: https://lists.openembedded.org/mt/118593422/1686489
> Group Owner: bitbake-devel+owner@lists.openembedded.org
> Unsubscribe: https://lists.openembedded.org/g/bitbake-devel/unsub [
> alex.kanavin@gmail.com]
> -=-=-=-=-=-=-=-=-=-=-=-
>
>

[-- Attachment #2: Type: text/html, Size: 8265 bytes --]

Re: [bitbake-devel] [docs] [PATCH 1/2] bitbake-setup: rename "abort" rebase conflict stragegy to "halt"

[Antonin Godard]

On Tue Mar 31, 2026 at 1:36 PM CEST, Alexander Kanavin wrote:
> There’s a simpler rationale too: this follows ‘git rebase —abort’. If git
> upstream finds a better word, we will follow. And I agree that all of the
> proposed alternatives are less accurate.

This goes against previous efforts to convert the documentation and other
components to not use these words :/
https://lists.openembedded.org/g/openembedded-architecture/topic/inclusive_language_summary/75821819

[...]
>> > This is not what halt means. Maybe 'reset' would be a better choice? Or
>> > if you really want to follow the recommendations from that website, I
>> > guess "cancel"?
>>
>> The trouble is none of these alternatives really match what abort
>> means, reset and cancel do mean something different. "abandon" might be
>> closer but still isn't right. "attempt" maybe? If we get too creative
>> with this, users just won't understand what it means :(

I had the impression, from the documentation, that bitbake-setup would leave the
repository in the middle of a rebase, to let you deal with conflict, and then
continue on the next bitbake-setup update call.

It appears to use --abort instead, so a misunderstanding from my part.

Out of these options, I think "reset" might be the best one, I agree with
Quentin. But I'm not a native speaker, so I might not have an understanding as
subtle as others.

I'll let Richard decide on what to do here.

Antonin

Re: [bitbake-devel] [docs] [PATCH 1/2] bitbake-setup: rename "abort" rebase conflict stragegy to "halt"

[Alexander Kanavin]

[-- Attachment #1: Type: text/plain, Size: 2543 bytes --]

The trouble with ‘reset’ is that it means resetting the whole system to its
initial state. ‘Abort’ is about a stopping a particular operation such that
the system is returned to the state before the operation started.

I have no idea how INI has utterly failed to catch these nuances in its
rationale you linked, and is even accusing the term of ‘lacking technical
clarity’, but it certainly doesn’t help the cause.

Alex


On Fri 3. Apr 2026 at 10.07, Antonin Godard via lists.yoctoproject.org
<antonin.godard=bootlin.com@lists.yoctoproject.org> wrote:

> On Tue Mar 31, 2026 at 1:36 PM CEST, Alexander Kanavin wrote:
> > There’s a simpler rationale too: this follows ‘git rebase —abort’. If git
> > upstream finds a better word, we will follow. And I agree that all of the
> > proposed alternatives are less accurate.
>
> This goes against previous efforts to convert the documentation and other
> components to not use these words :/
>
> https://lists.openembedded.org/g/openembedded-architecture/topic/inclusive_language_summary/75821819
>
> [...]
> >> > This is not what halt means. Maybe 'reset' would be a better choice?
> Or
> >> > if you really want to follow the recommendations from that website, I
> >> > guess "cancel"?
> >>
> >> The trouble is none of these alternatives really match what abort
> >> means, reset and cancel do mean something different. "abandon" might be
> >> closer but still isn't right. "attempt" maybe? If we get too creative
> >> with this, users just won't understand what it means :(
>
> I had the impression, from the documentation, that bitbake-setup would
> leave the
> repository in the middle of a rebase, to let you deal with conflict, and
> then
> continue on the next bitbake-setup update call.
>
> It appears to use --abort instead, so a misunderstanding from my part.
>
> Out of these options, I think "reset" might be the best one, I agree with
> Quentin. But I'm not a native speaker, so I might not have an
> understanding as
> subtle as others.
>
> I'll let Richard decide on what to do here.
>
> Antonin
>
> -=-=-=-=-=-=-=-=-=-=-=-
> Links: You receive all messages sent to this group.
> View/Reply Online (#9173):
> https://lists.yoctoproject.org/g/docs/message/9173
> Mute This Topic: https://lists.yoctoproject.org/mt/118594590/1686489
> Group Owner: docs+owner@lists.yoctoproject.org
> Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [
> alex.kanavin@gmail.com]
> -=-=-=-=-=-=-=-=-=-=-=-
>
>

[-- Attachment #2: Type: text/html, Size: 3859 bytes --]

Re: [bitbake-devel] [docs] [PATCH 1/2] bitbake-setup: rename "abort" rebase conflict stragegy to "halt"

[Richard Purdie]

On Fri, 2026-04-03 at 12:04 +0200, Alexander Kanavin wrote:
> The trouble with ‘reset’ is that it means resetting the whole system
> to its initial state. ‘Abort’ is about a stopping a particular
> operation such that the system is returned to the state before the
> operation started.
> 
> I have no idea how INI has utterly failed to catch these nuances in
> its rationale you linked, and is even accusing the term of ‘lacking
> technical clarity’, but it certainly doesn’t help the cause.

"reset" also struggles as "git reset" means something quite different.

"attempt" is probably the closest other option we have since that
describes what it does rather than the way it recovers, the recovery is
then just implied.

I am torn on this, I recognise the concern around the word, equally,
the word does have two meanings and we do clearly fit one of the cases,
as Alex mentions, we are inheriting the issue from git too. I fear any
change we make here will hurt usability.

Cheers,

Richard

[PATCH 2/2] doc/bitbake-user-manual-environment-setup.rst: replace shell blocks by console

[Antonin Godard]

The appropriate lexer to use for command examples is console, not shell.
Replace all misuses of this lexer in this document.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 .../bitbake-user-manual-environment-setup.rst      | 30 +++++++++++-----------
 1 file changed, 15 insertions(+), 15 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 c7b73001404..ece872ad26c 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst
@@ -27,7 +27,7 @@ Quick Start
 
 #. If you haven't already, clone the BitBake repository:
 
-   .. code-block:: shell
+   .. code-block:: console
 
       $ git clone https://git.openembedded.org/bitbake
 
@@ -36,7 +36,7 @@ Quick Start
 
    To start, run:
 
-   .. code-block:: shell
+   .. code-block:: console
 
       $ ./bitbake/bin/bitbake-setup init
 
@@ -94,7 +94,7 @@ Quick Start
 #. Source the ``init-build-env`` file present in the :term:`BitBake Build`
    directory:
 
-   .. code-block:: shell
+   .. code-block:: console
 
       $ source ./poky-master-poky-distro_poky-machine_qemux86-64/build/init-build-env
 
@@ -343,7 +343,7 @@ In addition, the command can take the following arguments:
 -  This example prompts the user to choose a :term:`Configuration Template` from
    a custom registry:
 
-   .. code-block:: shell
+   .. code-block:: console
 
       $ ./bitbake/bin/bitbake-setup \
           --setting default registry 'git://example.com/bitbake-setup-configurations.git;protocol=https;branch=main;rev=main' \
@@ -352,7 +352,7 @@ In addition, the command can take the following arguments:
 -  This example takes a :term:`Configuration Template` from a remote location
    (here, one of the default configuration in BitBake):
 
-   .. code-block:: shell
+   .. code-block:: console
 
       $ ./bitbake/bin/bitbake-setup init https://git.openembedded.org/bitbake/plain/default-registry/configurations/oe-nodistro-master.conf.json
 
@@ -363,7 +363,7 @@ In addition, the command can take the following arguments:
    -  A standalone :term:`Configuration Template` file.
    -  Choices passed on the command-line, applied non-interactively.
 
-   .. code-block:: shell
+   .. code-block:: console
 
       $ ./bitbake/bin/bitbake-setup \
           --setting default top-dir-prefix /work/bitbake-setup \
@@ -477,7 +477,7 @@ In addition, the command can take the following arguments:
    environment. Local commits in any layer directory are rebased on top of
    the new upstream revision and preserved:
 
-   .. code-block:: shell
+   .. code-block:: console
 
       $ bitbake-setup update
       NOTE: Bitbake-setup is using /path/to/bitbake-builds as top directory.
@@ -493,7 +493,7 @@ In addition, the command can take the following arguments:
 -  This example shows what happens when a layer directory contains staged or
    unstaged changes to tracked files. The update is blocked with an error:
 
-   .. code-block:: shell
+   .. code-block:: console
 
       $ bitbake-setup update
       NOTE: Bitbake-setup is using /path/to/bitbake-builds as top directory.
@@ -515,7 +515,7 @@ In addition, the command can take the following arguments:
 
    Stashing the changes and re-running resolves the issue:
 
-   .. code-block:: shell
+   .. code-block:: console
 
       $ git -C layers/openembedded-core stash
       $ bitbake-setup update
@@ -526,7 +526,7 @@ In addition, the command can take the following arguments:
    is automatically halted, and the ``dldir`` remote is left in the repository
    for manual resolution:
 
-   .. code-block:: shell
+   .. code-block:: console
 
       $ bitbake-setup update
       ERROR: Repository at layers/openembedded-core has local commits that could
@@ -539,7 +539,7 @@ In addition, the command can take the following arguments:
    The conflict can be resolved manually using the ``dldir`` remote that
    ``bitbake-setup`` adds to the repository:
 
-   .. code-block:: shell
+   .. code-block:: console
 
       $ git -C layers/openembedded-core rebase dldir/master
       # fix conflicts in an editor, then stage the resolved files:
@@ -552,7 +552,7 @@ In addition, the command can take the following arguments:
    preserves the conflicting directory under a timestamped backup path and
    re-clones the layer cleanly from upstream:
 
-   .. code-block:: shell
+   .. code-block:: console
 
       $ bitbake-setup update --rebase-conflicts-strategy=backup
       NOTE: Bitbake-setup is using /path/to/bitbake-builds as top directory.
@@ -583,7 +583,7 @@ In addition, the command can take the following arguments:
    the following commands can be used to apply these commits on top of the new
    upstream revision in the fresh clone:
 
-   .. code-block:: shell
+   .. code-block:: console
 
       $ git -C layers/openembedded-core-backup.20260329160426 log --oneline my-wip
       a1b2c3d u-boot: fix compilation with newer GCC
@@ -620,7 +620,7 @@ In addition, the command can take the following arguments:
    Once all desired commits have been recovered and verified, the backup
    directory can be removed:
 
-   .. code-block:: shell
+   .. code-block:: console
 
       $ rm -rf layers/openembedded-core-backup.20260329160426
 
@@ -856,7 +856,7 @@ These files are written in the JSON file format and are stored in a
 :term:`Registry`. They can also be standalone files directly passed to the
 :ref:`ref-bbsetup-command-init` command:
 
-.. code-block:: shell
+.. code-block:: console
 
    $ bitbake-setup init /path/to/config.conf.json
 

-- 
2.53.0