Prevent confusion about "priority"

For the openQA "priority" higher numbers mean actually "less priority"
so we considered different words to use, e.g. "niceness" as described on
https://en.wikipedia.org/wiki/Nice_%28Unix%29 but is also a very
Unix-specific concept. We might prefer more generic terms. Also such
rename would be a breaking change and would need to provide
backward-compatibility and/or a migration path.

Instead here I opted in documentation, help texts and comments to better
express that the specified value is *only* a value and not the priority
per se which is computed internally based on multiple factors.

This commit also adds a help text for the two -/+ buttons where
previously was no help text at all.

This commit was motivated by recurring user questions about the meaning
and the wish to clarify.

assets/javascripts/tests.js

@@ -187,7 +187,7 @@ function changeJobPrio(jobId, delta, linkElement) {
       prioValueElement.text(newPrio);
     },
     error: function (xhr, ajaxOptions, thrownError) {
-      addFlash('danger', 'Unable to set the priority of job ' + jobId + '.');
+      addFlash('danger', 'Unable to set the priority value of job ' + jobId + '.');
     }
   });
 }

docs/UsersGuide.asciidoc

@@ -163,13 +163,13 @@ and/or os-autoinst's own behavior are:
 
 The job groups are the place where the actual test scenarios are defined by
 the selection of the medium type, the test suite and machine together with a
-priority.
+priority value.
 
-The priority is used in the scheduler to choose the next job. If multiple jobs
-are scheduled and their requirements for running them are fulfilled the ones
-with a lower value for the priority are triggered. The id is the second
-sorting key: Of two jobs with equal requirements and same priority the one
-with lower id is triggered first.
+The priority value is used in the scheduler to choose the next job. If
+multiple jobs are scheduled and their requirements for running them are
+fulfilled the ones with a lower priority value are triggered. The id is the
+second sorting key: Of two jobs with equal requirements and same priority
+value the one with lower id is triggered first.
 
 Job groups themselves can be created over the web UI as well as the REST API.
 Job groups can optionally be nested into categories. The display order of job
@@ -228,7 +228,7 @@ order for variables is as follows (from lowest to highest):
 That is, variable values set as part of the API request that triggers the jobs will
 'win' over values set at any of the other locations. In the special case of the 
 `BACKEND` variable, if there is a `MACHINE` specified, the `BACKEND` value for this
-machine defined in openQA has highest priority.
+machine defined in openQA has highest precedence.
 
 If you need to override this precedence - for example, you want the value set in
 one particular test suite to take precedence over a setting of the same value from
@@ -982,11 +982,12 @@ _OBSOLETE:: Obsolete jobs in older builds with same DISTRI and VERSION
 (The default behavior is not obsoleting). With this option jobs which are currently pending,
 for example scheduled or running, are cancelled when a new medium is triggered.
 
-_DEPRIORITIZEBUILD:: Setting this switch to '1' will deprioritize the unfinished jobs of old
-builds, and it will obsolete the jobs once the configurable limit of priority is reached.
+_DEPRIORITIZEBUILD:: Setting this switch to '1' will deprioritize the
+unfinished jobs of old builds, and it will obsolete the jobs once the
+configurable limit of the priority value is reached.
 
-_DEPRIORITIZE_LIMIT:: The configurable limit of priority up to which jobs
-should be deprioritized. Needs `_DEPRIORITIZEBUILD`. Default 100.
+_DEPRIORITIZE_LIMIT:: The configurable limit of priority value up to which
+jobs should be deprioritized. Needs `_DEPRIORITIZEBUILD`. Defaults to 100.
 
 _ONLY_OBSOLETE_SAME_BUILD:: Only obsolete (or deprioritize) jobs for the same BUILD.
 This is useful for cases where a new build appearing does not necessarily
@@ -1001,8 +1002,8 @@ _GROUP:: Job templates *not* matching the given group name are ignored. Does *no
          affect obsoletion behavior.
 
 _GROUP_ID:: Same as `_GROUP` but allows to specify the group directly by ID.
-_PRIORITY:: Sets the priority for the new jobs (which otherwise defaults to the priority
-            of the job template)
+_PRIORITY:: Sets the priority value for the new jobs (which otherwise defaults
+to the priority of the job template)
 
 Example for `_DEPRIORITIZEBUILD` and `_DEPRIORITIZE_LIMIT`.
 

lib/OpenQA/Scheduler/Model/Jobs.pm

@@ -19,7 +19,7 @@ use List::Util qw(all shuffle);
 # How many jobs to allocate in one tick. Defaults to 80 ( set it to 0 for as much as possible)
 use constant MAX_JOB_ALLOCATION => $ENV{OPENQA_SCHEDULER_MAX_JOB_ALLOCATION} // 80;
 
-# How much the priority should be increased (the priority number decreased) to protect a parallel cluster from starvation
+# How much the priority should be increased (the priority value decreased) to protect a parallel cluster from starvation
 use constant STARVATION_PROTECTION_PRIORITY_OFFSET => $ENV{OPENQA_SCHEDULER_STARVATION_PROTECTION_PRIORITY_OFFSET} // 1;
 
 has scheduled_jobs => sub { {} };

public/schema/JobTemplates-01.yaml

@@ -30,7 +30,7 @@ properties:
                 description: Name of a test suite name
               - type: object
                 maxProperties: 1
-                description: A test suite with machine and/ or priority specified, or a custom job template name if testsuite was specified
+                description: A test suite with machine and/or priority value specified, or a custom job template name if testsuite was specified
                 additionalProperties: false
                 patternProperties:
                   &testsuite-pattern '^[A-Za-z\s0-9_*.+-]+$':

t/data/job-templates/schema-invalid.yaml

@@ -25,7 +25,7 @@ properties:
                 description: Name of a test suite name
               - type: object
                 maxProperties: 1
-                description: A test suite with machine and/ or priority specified, or a custom job template name if testsuite was specified
+                description: A test suite with machine and/or priority value specified, or a custom job template name if testsuite was specified
                 additionalProperties: false
                 patternProperties:
                   "^[A-Za-z\\s0-9_*.+-]+$":

templates/webapi/test/infopanel.html.ep

@@ -125,11 +125,11 @@
                 % if ($job->state eq SCHEDULED) {
                     <div>
                         <a class="prio-down" data-method="post" href="javascript:void(0);" onclick="decreaseJobPrio(<%= $job->id %>, this);">
-                            <i class="fa fa-minus-square-o"></i>
+                            <i class="fa fa-minus-square-o" title="Decrease priority value (higher precedence)"></i>
                         </a>
                         <span class="prio-value"><%= $job->priority %></span>
                         <a class="prio-up" data-method="post" href="javascript:void(0);" onclick="increaseJobPrio(<%= $job->id %>, this);">
-                            <i class="fa fa-plus-square-o"></i>
+                            <i class="fa fa-plus-square-o" title="Increase priority value (lower precedence)"></i>
                         </a>
                     </div>
                 % }