Repository: canonical/snapcraft

Issue:
Apply guidelines from design to error messages with commands that fix
pr: #1790
Estimate: 1 day


Discussion:

Resolving patch:
diff --git a/snapcraft/internal/errors.py b/snapcraft/internal/errors.py
--- a/snapcraft/internal/errors.py
+++ b/snapcraft/internal/errors.py
@@ -41,7 +41,7 @@ class MissingStateCleanError(SnapcraftError):
     fmt = (
         "Failed to clean: "
         "Missing state for {step!r}. "
-        "This won't work until a complete clean has occurred."
+        "To clean the project, run `snapcraft clean`."
     )
 
     def __init__(self, step):
@@ -54,9 +54,8 @@ class StepOutdatedError(SnapcraftError):
         'Failed to reuse files from previous build: '
         'The {step!r} step of {part!r} is out of date:\n'
         '{report}'
-        'To continue, please clean that part\'s {step!r} step '
-        'by running:\n'
-        'snapcraft clean {parts_names} -s {step}\n'
+        'To continue, clean that part\'s {step!r} step, run '
+        '`snapcraft clean {parts_names} -s {step}`.'
     )
 
     def __init__(self, *, step, part,
@@ -267,8 +266,8 @@ class SnapcraftPartConflictError(SnapcraftError):
         '    - `stage`\n'
         '    - `snap`\n'
         '    - `organize`\n\n'
-        'Learn more about these part keywords by running '
-        '`snapcraft help plugins`'
+        'To learn more about these part keywords, run '
+        '`snapcraft help plugins`.'
     )
 
     def __init__(self, *, part_name, other_part_name, conflict_files):


Test patch:
diff --git a/snapcraft/tests/integration/general/test_stage.py b/snapcraft/tests/integration/general/test_stage.py
--- a/snapcraft/tests/integration/general/test_stage.py
+++ b/snapcraft/tests/integration/general/test_stage.py
@@ -49,8 +49,8 @@ def _stage_conflicts(self, debug):
             '    - `stage`\n'
             '    - `snap`\n'
             '    - `organize`\n\n'
-            'Learn more about these part keywords by running '
-            '`snapcraft help plugins`'
+            'To learn more about these part keywords, run '
+            '`snapcraft help plugins`.'
         )
         self.assertThat(exception.output, Contains(expected_help))
         return exception.output
@@ -82,8 +82,8 @@ def test_conflicts(self):
             '    - `stage`\n'
             '    - `snap`\n'
             '    - `organize`\n\n'
-            'Learn more about these part keywords by running '
-            '`snapcraft help plugins`'
+            'To learn more about these part keywords, run '
+            '`snapcraft help plugins`.'
         )
         self.assertThat(exception.output, Contains(expected_help))
 
diff --git a/snapcraft/tests/unit/test_errors.py b/snapcraft/tests/unit/test_errors.py
--- a/snapcraft/tests/unit/test_errors.py
+++ b/snapcraft/tests/unit/test_errors.py
@@ -29,7 +29,7 @@ class ErrorFormattingTestCase(unit.TestCase):
             'expected_message': (
                 "Failed to clean: "
                 "Missing state for 'test-step'. "
-                "This won't work until a complete clean has occurred."
+                "To clean the project, run `snapcraft clean`."
                 )}),
         ('StepOutdatedError dependents', {
             'exception': errors.StepOutdatedError,
@@ -43,9 +43,9 @@ class ErrorFormattingTestCase(unit.TestCase):
                 "The 'test-step' step of 'test-part' is out of date:\n"
                 "The 'test-step' step for 'test-part' needs to be run again, "
                 "but 'test-dependent' depends on it.\n"
-                "To continue, please clean that part's "
-                "'test-step' step by running:\n"
-                "snapcraft clean test-dependent -s test-step\n")}),
+                "To continue, clean that part's "
+                "'test-step' step, run "
+                "`snapcraft clean test-dependent -s test-step`.")}),
         ('StepOutdatedError dirty_properties', {
             'exception': errors.StepOutdatedError,
             'kwargs': {
@@ -58,9 +58,9 @@ class ErrorFormattingTestCase(unit.TestCase):
                 "The 'test-step' step of 'test-part' is out of date:\n"
                 "The 'test-property1' and 'test-property2' part properties "
                 "appear to have changed.\n"
-                "To continue, please clean that part's "
-                "'test-step' step by running:\n"
-                "snapcraft clean test-part -s test-step\n")}),
+                "To continue, clean that part's "
+                "'test-step' step, run "
+                "`snapcraft clean test-part -s test-step`.")}),
         ('StepOutdatedError dirty_project_options', {
             'exception': errors.StepOutdatedError,
             'kwargs': {
@@ -72,9 +72,9 @@ class ErrorFormattingTestCase(unit.TestCase):
                 "Failed to reuse files from previous build: "
                 "The 'test-step' step of 'test-part' is out of date:\n"
                 "The 'test-option' project option appears to have changed.\n"
-                "To continue, please clean that part's "
-                "'test-step' step by running:\n"
-                "snapcraft clean test-part -s test-step\n")}),
+                "To continue, clean that part's "
+                "'test-step' step, run "
+                "`snapcraft clean test-part -s test-step`.")}),
         ('SnapcraftEnvironmentError', {
             'exception': errors.SnapcraftEnvironmentError,
             'kwargs': {'message': 'test-message'},
@@ -212,8 +212,8 @@ class ErrorFormattingTestCase(unit.TestCase):
                 "    - `snap`\n"
                 "    - `organize`\n"
                 "\n"
-                "Learn more about these part keywords by running "
-                "`snapcraft help plugins`")}),
+                "To learn more about these part keywords, run "
+                "`snapcraft help plugins`.")}),
         ('MissingCommandError', {
             'exception': errors.MissingCommandError,
             'kwargs': {