Rename cache-buildtrees option value 'failure' to 'auto'

We anticipate other cases than build failures where buildtree caching
will be required.  E.g., incremental workspace build with remote
execution. Or running tests in a buildtree in parallel with the build of
reverse dependencies.

This renames the option value 'failure' to the more generic 'auto' to
cover these other cases as well.

7 files changed, 9 insertions, 9 deletions

diff --git a/NEWS b/NEWS
index 85bf27c2c..5da4a1322 100644
--- a/NEWS
+++ b/NEWS
@@ -137,7 +137,7 @@ buildstream 1.3.1
     Element types without a build-root were already cached with an empty build tree
     directory, this can now be extended to all or successful artifacts to save on cache
     overheads. The cli main option '--cache-buildtrees' or the user configuration cache
-    group option 'cache-buildtrees' can be set as 'always', 'failure' or 'never', with
+    group option 'cache-buildtrees' can be set as 'always', 'auto' or 'never', with
     the default being always. Note, as the cache-key for the artifact is independant of
     the cached build tree input it will remain unaltered, however the availbility of the
     build tree content may differ.
diff --git a/buildstream/_context.py b/buildstream/_context.py
index 286e2d223..476032f39 100644
--- a/buildstream/_context.py
+++ b/buildstream/_context.py
@@ -269,7 +269,7 @@ class Context():
 
         # Load cache build trees configuration
         self.cache_buildtrees = _node_get_option_str(
-            cache, 'cache-buildtrees', ['always', 'failure', 'never'])
+            cache, 'cache-buildtrees', ['always', 'auto', 'never'])
 
         # Load logging config
         logging = _yaml.node_get(defaults, Mapping, 'logging')
diff --git a/buildstream/_frontend/cli.py b/buildstream/_frontend/cli.py
index 4974e2bfc..520624f59 100644
--- a/buildstream/_frontend/cli.py
+++ b/buildstream/_frontend/cli.py
@@ -255,7 +255,7 @@ def print_version(ctx, param, value):
 @click.option('--pull-buildtrees', is_flag=True, default=None,
               help="Include an element's build tree when pulling remote element artifacts")
 @click.option('--cache-buildtrees', default=None,
-              type=click.Choice(['always', 'failure', 'never']),
+              type=click.Choice(['always', 'auto', 'never']),
               help="Cache artifact build tree content on creation")
 @click.pass_context
 def cli(context, **kwargs):
diff --git a/buildstream/data/userconfig.yaml b/buildstream/data/userconfig.yaml
index 82a8b5890..e70c41312 100644
--- a/buildstream/data/userconfig.yaml
+++ b/buildstream/data/userconfig.yaml
@@ -41,7 +41,7 @@ cache:
   # Whether to cache build trees on artifact creation:
   #
   #  always  - Always cache artifact build tree content
-  #  failure - Only cache build trees of failed builds
+  #  auto    - Only cache build trees when necessary, e.g., for failed builds
   #  never   - Never cache artifact build tree content. This is not recommended
   #            for normal users as this breaks core functionality such as
   #            debugging failed builds and may break additional functionality
diff --git a/buildstream/element.py b/buildstream/element.py
index 43bbd6939..45bb983bb 100644
--- a/buildstream/element.py
+++ b/buildstream/element.py
@@ -1724,7 +1724,7 @@ class Element(Plugin):
         cache_buildtrees = context.cache_buildtrees
         build_success = buildresult[0]
 
-        if cache_buildtrees == 'always' or (cache_buildtrees == 'failure' and not build_success):
+        if cache_buildtrees == 'always' or (cache_buildtrees == 'auto' and not build_success):
             try:
                 sandbox_build_dir = sandbox_vroot.descend(
                     *self.get_variable('build-root').lstrip(os.sep).split(os.sep))
diff --git a/tests/frontend/completions.py b/tests/frontend/completions.py
index 7810a06d5..6c737924d 100644
--- a/tests/frontend/completions.py
+++ b/tests/frontend/completions.py
@@ -158,7 +158,7 @@ def test_options(cli, cmd, word_idx, expected):
 
 @pytest.mark.parametrize("cmd,word_idx,expected", [
     ('bst --on-error ', 2, ['continue ', 'quit ', 'terminate ']),
-    ('bst --cache-buildtrees ', 2, ['always ', 'failure ', 'never ']),
+    ('bst --cache-buildtrees ', 2, ['always ', 'auto ', 'never ']),
     ('bst show --deps ', 3, ['all ', 'build ', 'none ', 'plan ', 'run ']),
     ('bst show --deps=', 2, ['all ', 'build ', 'none ', 'plan ', 'run ']),
     ('bst show --deps b', 3, ['build ']),
diff --git a/tests/integration/shellbuildtrees.py b/tests/integration/shellbuildtrees.py
index 31af8a0e4..8c5411526 100644
--- a/tests/integration/shellbuildtrees.py
+++ b/tests/integration/shellbuildtrees.py
@@ -154,19 +154,19 @@ def test_buildtree_from_failure_option_never(cli_integration, tmpdir, datafiles)
 
 @pytest.mark.datafiles(DATA_DIR)
 @pytest.mark.skipif(not HAVE_SANDBOX, reason='Only available with a functioning sandbox')
-def test_buildtree_from_failure_option_failure(cli_integration, tmpdir, datafiles):
+def test_buildtree_from_failure_option_auto(cli_integration, tmpdir, datafiles):
 
     project = os.path.join(datafiles.dirname, datafiles.basename)
     element_name = 'build-shell/buildtree-fail.bst'
 
-    # build with  --cache-buildtrees set to 'failure', behaviour should match
+    # build with  --cache-buildtrees set to 'auto', behaviour should match
     # default behaviour (which is always) as the buildtree will explicitly have been
     # cached with content.
     cli_integration.configure({
         'cachedir': str(tmpdir)
     })
 
-    res = cli_integration.run(project=project, args=['--cache-buildtrees', 'failure', 'build', element_name])
+    res = cli_integration.run(project=project, args=['--cache-buildtrees', 'auto', 'build', element_name])
     res.assert_main_error(ErrorDomain.STREAM, None)
 
     res = cli_integration.run(project=project, args=[