From 510ddaf8d0832dc4c8717da4c014a618f8ee56b5 Mon Sep 17 00:00:00 2001
From: Mohamed Bilel Besrour <58034472+BBesrour@users.noreply.github.com>
Date: Sun, 28 Jul 2024 22:50:32 +0200
Subject: [PATCH] Development: Update priority calculation docs (#9138)

---
 ...ntegrated-code-lifecycle-system-design.inc | 23 +++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)

diff --git a/docs/dev/system-design/integrated-code-lifecycle/integrated-code-lifecycle-system-design.inc b/docs/dev/system-design/integrated-code-lifecycle/integrated-code-lifecycle-system-design.inc
index 7bd9f444be0c..3aaf3e358897 100644
--- a/docs/dev/system-design/integrated-code-lifecycle/integrated-code-lifecycle-system-design.inc
+++ b/docs/dev/system-design/integrated-code-lifecycle/integrated-code-lifecycle-system-design.inc
@@ -79,8 +79,8 @@ The CI Management has access to the database and the file system.
 
 
 The CI Management subsystem implements the ``ContinuousIntegrationTriggerService`` interface, the ``LocalCITriggerService`` which provides the ``triggerBuild`` method. This method gets called whenever a repository needs to be tested, i.e. after creating a programming exercise or when a student submits code.
-When the ``triggerBuild`` method is called, all necessary information necessary to execute the build job is prepared and used to create a ``LocalCIBuildJobQueueItem`` object. The object contains, among other things, repository URIs, the build configuration, a user-defined build script (prepared by the ``LocalCIScriptService``) and a priority value.
-The priority value is determined based on whether the programming exercise is part of an exam or not. The exercise due date is also taken into account. This object is then added to the job queue where it will then be retrieved by a build agent to execute the build job. The following diagram shows the structure of the ``LocalCIBuildJobQueueItem``:
+When the ``triggerBuild`` method is called, all information necessary to execute the build job is prepared and used to create a ``LocalCIBuildJobQueueItem`` object. The object contains, among other things, repository URIs, the build configuration, a user-defined build script (prepared by the ``LocalCIScriptService``) and a priority value (more details :ref:`here <ci_priority>`).
+The exercise due date is also taken into account. This object is then added to the job queue where it will be retrieved by a build agent to execute the build job. The following diagram shows the structure of the ``LocalCIBuildJobQueueItem``:
 
 .. figure:: /dev/system-design/integrated-code-lifecycle/Integrated_Code_Lifecycle_Build_Job_Item.svg
    :align: center
@@ -95,6 +95,25 @@ The service provides the functionality for an Artemis user to interact with buil
 The user can access this functionality using the UI over a set of endpoints provided by a REST API.
 The ``LocalCIResultProcessingService`` retrieves the build job results which were generated by the build agents from the result queue. It is responsible for grading the build job results, notifying the user and persisting information on the build job execution in the database.
 
+.. _ci_priority:
+
+Priority Calculation
+""""""""""""""""""""
+Build jobs are assigned a priority value when they are added to the job queue. This value is used to determine the order in which build jobs are executed.
+The higher the priority value, the sooner the build job is executed.
+
+The priority value is determined based on several factors related to the programming exercise and its context.
+Exercises that are part of an ongoing exam are given the highest priority of ``1`` to ensure quick feedback.
+Exam exercises that are part of a test exam or a test run within an exam are assigned a priority of ``2``.
+Submissions made after the due date, such as those in practice mode or finished exams, receive a lower priority of ``3``.
+Optional exercises, which are not included in the overall score, are also assigned a priority of ``3``.
+If the build is part of a batch, for example, if an instructor triggers a re-build of all submissions of an exercise, it is assigned the lowest priority of ``4``.
+If none of the above conditions apply, for example, exercises that are part of a real course and not part of an exam, the priority is set to ``2``.
+Additionally, if the exercise is part of a test course, a penalty is added to the priority, making it less urgent. The penalty is implemented by adding a value of ``5`` to the priority.
+The priority calculation is implemented in the ``LocalCITriggerService``.
+
+
+
 Build Agent
 ^^^^^^^^^^^