Document predefined order values of special phases

I threw in a bit of renaming, because some constants were not about
plugins only, some were not defaults, i.e. it was not possible to change
them, and so on.

spec/core/order.fmf

@@ -1,3 +1,6 @@
+/:
+    select: true
+
 summary: Order in which the object should be handled
 
 description:
@@ -14,3 +17,26 @@ example: |
 link:
   - implemented-by: /tmt/base.py
   - verified-by: /tests/core/order
+
+/predefined-order:
+    title: Predefined order values
+
+    summary: Predefined order values - summary
+
+    description: |
+        30
+            Installation of essential plugin and check requirements.
+
+        50
+            The default order of any object.
+
+        60
+            Application of patches by ``rpm-build`` command invoked by
+            :ref:`discover/fmf</plugins/discover/fmf>` plugin when
+            ``dist-git-source`` key is used.
+
+        70
+            Installation of packages :ref:`required</spec/tests/require>` by tests.
+
+        75
+            Installation of packages :ref:`recommended</spec/tests/recommend>` by tests.

tmt/base.py

@@ -88,6 +88,7 @@
 # metadata and 1h for scripts defined directly in plans (L2 metadata).
 DEFAULT_TEST_DURATION_L1 = '5m'
 DEFAULT_TEST_DURATION_L2 = '1h'
+#: The default order of any object.
 DEFAULT_ORDER = 50
 
 DEFAULT_TEST_RESTART_LIMIT = 1

tmt/steps/__init__.py

@@ -68,8 +68,25 @@
 
 
 DEFAULT_ALLOWED_HOW_PATTERN: Pattern[str] = re.compile(r'.*')
-DEFAULT_PLUGIN_METHOD_ORDER: int = 50
 
+#
+# Following are default and predefined order values for various special phases
+# recognized by tmt. When adding new special phase, add its order below, and
+# do not forget to update the list in /spec/core/order. Please, keep the name
+# prefix, so it's easy to find all `PHASE_ORDER_*` constants for documentation.
+#
+
+#: The default order of any object.
+# TODO: this is a duplication of tmt.base.DEFAULT_ORDER. Unfortunately, tmt.base
+# imports tmt.steps, not the other way around.
+# `PHASE_ORDER_DEFAULT = tmt.base.DEFAULT_ORDER` would be way better.
+PHASE_ORDER_DEFAULT = 50
+#: Installation of essential plugin and check requirements.
+PHASE_ORDER_INSTALL_ESSENTIAL_REQUIRES = 30
+#: Installation of packages :ref:`required</spec/tests/require>` by tests.
+PHASE_ORDER_INSTALL_REQUIRES = 70
+#: Installation of packages :ref:`recommended</spec/tests/recommend>` by tests.
+PHASE_ORDER_INSTALL_RECOMMENDS = 75
 
 # Supported steps and actions
 STEPS: list[str] = ['discover', 'provision', 'prepare', 'execute', 'report', 'finish']
@@ -122,7 +139,7 @@
     option(
         '--order',
         type=int,
-        default=DEFAULT_PLUGIN_METHOD_ORDER,
+        default=PHASE_ORDER_DEFAULT,
         help='Order in which the phase should be handled.')
     ])
 
@@ -189,7 +206,7 @@ class Phase(tmt.utils.Common):
     def __init__(
             self,
             *,
-            order: int = tmt.utils.DEFAULT_PLUGIN_ORDER,
+            order: int = PHASE_ORDER_DEFAULT,
             **kwargs: Any):
         super().__init__(**kwargs)
         self.order: int = order
@@ -291,7 +308,7 @@ class StepData(
     name: str = field(help='The name of the step phase.')
     how: str = field()
     order: int = field(
-        default=tmt.utils.DEFAULT_PLUGIN_ORDER,
+        default=PHASE_ORDER_DEFAULT,
         help='Order in which the phase should be handled.')
     when: list[str] = field(
         default_factory=list,
@@ -1170,7 +1187,7 @@ def __init__(
             name: str,
             class_: Optional[PluginClass] = None,
             doc: Optional[str] = None,
-            order: int = DEFAULT_PLUGIN_METHOD_ORDER
+            order: int = PHASE_ORDER_DEFAULT
             ) -> None:
         """ Store method data """
 
@@ -1213,7 +1230,7 @@ def usage(self) -> str:
 def provides_method(
         name: str,
         doc: Optional[str] = None,
-        order: int = DEFAULT_PLUGIN_METHOD_ORDER) -> Callable[[PluginClass], PluginClass]:
+        order: int = PHASE_ORDER_DEFAULT) -> Callable[[PluginClass], PluginClass]:
     """
     A plugin class decorator to register plugin's method with tmt steps.
 
@@ -1579,7 +1596,7 @@ def _emit_key(key: str) -> None:
             value = self.get(key)
 
             # No need to show the default order
-            if key == 'order' and value == tmt.base.DEFAULT_ORDER:
+            if key == 'order' and value == PHASE_ORDER_DEFAULT:
                 return
 
             if value is None:

tmt/steps/discover/shell.py

@@ -60,7 +60,7 @@ class TestDescription(
     description: Optional[str] = None
     enabled: bool = True
     order: int = field(
-        # TODO: ugly circular dependency (see tmt.base.DEFAULT_ORDER)
+        # TODO: ugly circular dependency (see tmt.steps.PHASE_ORDER_DEFAULT)
         default=50,
         normalize=lambda key_address, raw_value, logger:
             50 if raw_value is None else int(raw_value)

tmt/steps/prepare/__init__.py

@@ -343,19 +343,19 @@ def _emit_phase(
             pruned_essential_requires,
             'essential-requires',
             'Install essential required packages',
-            tmt.utils.DEFAULT_PLUGIN_ORDER_ESSENTIAL_REQUIRES)
+            tmt.steps.PHASE_ORDER_INSTALL_ESSENTIAL_REQUIRES)
 
         _emit_phase(
             pruned_requires,
             'requires',
             'Install required packages',
-            tmt.utils.DEFAULT_PLUGIN_ORDER_REQUIRES)
+            tmt.steps.PHASE_ORDER_INSTALL_REQUIRES)
 
         _emit_phase(
             pruned_recommends,
             'recommends',
             'Install recommended packages',
-            tmt.utils.DEFAULT_PLUGIN_ORDER_RECOMMENDS,
+            tmt.steps.PHASE_ORDER_INSTALL_RECOMMENDS,
             missing='skip')
 
         # Prepare guests (including workdir sync)

tmt/steps/prepare/distgit.py

@@ -19,6 +19,11 @@
     import tmt.steps.discover
     import tmt.steps.prepare.install
 
+#: Application of patches by ``rpm-build`` command invoked by
+#: :ref:`discover/fmf</plugins/discover/fmf>` plugin when
+#: ``dist-git-source`` key is used.
+PHASE_ORDER_RPMBUILD_BP = 30
+
 PREPARE_WRAPPER_FILENAME = 'tmt-prepare-wrapper.sh'
 
 FEDORA_BUILD_REQUIRES = [Package('@buildsys-build')]
@@ -59,7 +64,7 @@ def insert_to_prepare_step(
         how='install',
         name='requires (dist-git)',
         summary='Install required packages of tests detected by dist-git',
-        order=tmt.utils.DEFAULT_PLUGIN_ORDER_REQUIRES,
+        order=tmt.steps.PHASE_ORDER_INSTALL_REQUIRES,
         where=where,
         package=[])
     future_requires: PreparePlugin[Any] = cast(
@@ -72,7 +77,7 @@ def insert_to_prepare_step(
         how='install',
         name='recommends (dist-git)',
         summary='Install recommended packages of tests detected by dist-git',
-        order=tmt.utils.DEFAULT_PLUGIN_ORDER_RECOMMENDS,
+        order=tmt.steps.PHASE_ORDER_INSTALL_RECOMMENDS,
         where=where,
         package=[],
         missing='skip')
@@ -116,7 +121,7 @@ class DistGitData(tmt.steps.prepare.PrepareStepData):
         option='--phase-name',
         help="Name of the discover step phase to inject tests to.",
         internal=True)
-    order: int = 60
+    order: int = PHASE_ORDER_RPMBUILD_BP
     install_builddeps: bool = field(
         default=False,
         option="--install-builddeps",

tmt/utils/__init__.py

@@ -141,13 +141,8 @@ def configure_constant(default: int, envvar: str) -> int:
 # Hierarchy indent
 INDENT = 4
 
-# Default name and order for step plugins
+# Default name for step plugins
 DEFAULT_NAME = 'default'
-DEFAULT_PLUGIN_ORDER = 50
-DEFAULT_PLUGIN_ORDER_MULTIHOST = 10
-DEFAULT_PLUGIN_ORDER_ESSENTIAL_REQUIRES = 30
-DEFAULT_PLUGIN_ORDER_REQUIRES = 70
-DEFAULT_PLUGIN_ORDER_RECOMMENDS = 75
 
 
 # Special process return codes