| Message ID | 20260331-docs-fixes-v1-1-45ee34341e72@bootlin.com |
|---|---|
| State | New |
| Headers | show |
| Series | bitbake-setup docs fixes | expand |
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
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
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] > -=-=-=-=-=-=-=-=-=-=-=- > >
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")
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(-)