From 8979e9dbb6c2e5b02220100132604f50d683b500 Mon Sep 17 00:00:00 2001
From: Orestis <orestis.malaspinas@pm.me>
Date: Wed, 20 Sep 2023 17:33:44 +0200
Subject: [PATCH] added cli exercise doc
---
Wiki/CLI-exercise-perform.md | 154 +++++++++++++++++++++++++++++++++++
Wiki/home.md | 6 +-
2 files changed, 159 insertions(+), 1 deletion(-)
create mode 100644 Wiki/CLI-exercise-perform.md
diff --git a/Wiki/CLI-exercise-perform.md b/Wiki/CLI-exercise-perform.md
new file mode 100644
index 0000000..b4f904c
--- /dev/null
+++ b/Wiki/CLI-exercise-perform.md
@@ -0,0 +1,154 @@
+# How to perform an exercise
+
+In this tutorial we quickly explain the workflow for performing an exercise by a student (or a professor).
+The exercise is based on the `c_hello_world` assignment.
+
+## Exercise "creation"
+
+To perform an exercise the student must first create the exercise. Under the hood, this operation consist in making
+a fork of a published assignment in the student's namespace.
+
+This is performed by the following `dojo` command:
+```bash
+$ dojo exercise create --assignment c_hello_world
+```
+```console
+Please wait while we verify and retrieve data...
+ℹ Checking Dojo session:
+ ✔ The session is valid
+ ✔ Student permissions
+ℹ Checking Gitlab token:
+ ✔ Read access
+ ✔ Write access
+ℹ Checking assignment:
+ ✔ Assignment "c_hello_world" exists
+ ✔ Assignment "c_hello_world" is published
+Please wait while we are creating the exercise...
+✔ Exercise successfully created
+ ℹ Id: 8d3f53a0-0d32-4455-a251-e1a1c5a97c6a
+ ℹ Name: DojoEx - c_hello_world - orestis.malaspin - 1
+ ℹ Web URL: https://gitedu.hesge.ch/dojo/exercise/dojo-ex_c_hello_world_8d3f53a0-0d32-4455-a251-e1a1c5a97c6a
+ ℹ HTTP Repo: https://gitedu.hesge.ch/dojo/exercise/dojo-ex_c_hello_world_8d3f53a0-0d32-4455-a251-e1a1c5a97c6a.git
+ ℹ SSH Repo: ssh://git@ssh.hesge.ch:10572/dojo/exercise/dojo-ex_c_hello_world_8d3f53a0-0d32-4455-a251-e1a1c5a97c6a.git
+```
+
+## To perform the exercise
+
+The exercise is nothing else than a git repository so the workflow is pretty straightforward.
+
+1. Clone the repository (see the repo link above)
+```bash
+$ git clone ssh://git@ssh.hesge.ch:10572/dojo/exercise/dojo-ex_c_hello_world_8d3f53a0-0d32-4455-a251-e1a1c5a97c6a.git
+```
+```console
+Cloning into 'dojo-ex_c_hello_world_8d3f53a0-0d32-4455-a251-e1a1c5a97c6a'...
+remote: Enumerating objects: 33, done.
+remote: Counting objects: 100% (33/33), done.
+remote: Compressing objects: 100% (26/26), done.
+remote: Total 33 (delta 6), reused 16 (delta 3), pack-reused 0
+Receiving objects: 100% (33/33), 7.32 KiB | 7.32 MiB/s, done.
+Resolving deltas: 100% (6/6), done.
+```
+2. Read the `README.md` file to understand what is expected by the teacher.
+3. Modify/create the appropriate code.
+4. (Optional but recommended) Execute the pipeline locally
+```bash
+$ dojo exercise run
+```
+```console
+Please wait while we are checking and creating dependencies...
+ ℹ Checking exercise content:
+ ✔ The exercise folder contains all the needed files
+ ✔ The dojo_assignment.json file is valid
+ ✔ The Docker deamon is running
+Please wait while we are running the exercise...
+ ✔ Docker Compose file run successfully
+ ✔ Linked services logs acquired
+ ✔ Containers stopped and removed
+Please wait while we are checking the results...
+ ✔ Results file found
+ ✔ Results file is valid
+ ✔ Results folder size is in bounds
+
+ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Results ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+ ┃ ┃
+ ┃ Global result : ❌ Failure ┃
+ ┃ ┃
+ ┃ Execution exit code : 0 ┃
+ ┃ ┃
+ ┃ Execution results folder : /home/student/DojoExecutions/dojo_execLogs_2023-08-30T18_58_05_764Z ┃
+ ┃ ┃
+ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+```
+Currently the exercise is a failure which is sad but expected since there was no modification in any file.
+One can see that we have access to a `results` folder in `/home/student/DojoExecutions/dojo_execLogs_2023-08-30T18_58_05_764Z`.
+This directory contains the output of the pipeline execution
+```console
+/home/student/DojoExecutions/dojo_execLogs_2023-08-30T18_58_05_764Z
+├── Dojo
+│ ├── dockerComposeLogs.txt
+│ └── results.json
+└── Exercise
+ └── diff_output.txt
+
+2 directories, 3 files
+```
+In particular one can find the output the teacher wanted us (students) to see in the `Exercise` folder.
+It contains any output file that can be used for debugging for example. In this case it contains
+```console
+< ./hello_world
+< (null)
+\ No newline at end of file
+---
+> Hello world!
+\ No newline at end of file
+```
+One can see that there is an `Hello world!` expected and that no `Hello world!` was provided by our program.
+One can also see the complete
+logs of the `docker compose` command in `Dojo/dockerComposeLogs.txt` which may (or may not)
+provide additional informations.
+
+In order to complete this assignment we have to modify the `src/function.c` file such that it becomes
+```c
+#include "function.h"
+
+char *hello_world()
+{
+ return "Hello world!";
+}
+```
+Rerunning the pipeline now yields
+```bash
+$ dojo exercise run
+```
+```console
+Please wait while we are checking and creating dependencies...
+ ℹ Checking exercise content:
+ ✔ The exercise folder contains all the needed files
+ ✔ The dojo_assignment.json file is valid
+ ✔ The Docker deamon is running
+Please wait while we are running the exercise...
+ ✔ Docker Compose file run successfully
+ ✔ Linked services logs acquired
+ ✔ Containers stopped and removed
+Please wait while we are checking the results...
+ ✔ Results file found
+ ✔ Results file is valid
+ ✔ Results folder size is in bounds
+
+ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Results ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+ ┃ ┃
+ ┃ Global result : ✅ Success ┃
+ ┃ ┃
+ ┃ Execution exit code : 0 ┃
+ ┃ ┃
+ ┃ Execution results folder : /home/student/DojoExecutions/dojo_execLogs_2023-08-30T19_20_25_104Z ┃
+ ┃ ┃
+ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+```
+5. Now that we are happy with the state of our exercise, we can commit and push our modifications and
+the exercise will be run through the Gitlab CI pipeline and one can see the "official" result
+of our exercise.
+
+It is not necessary to have a successful pipeline to commit and push the code. We can do it at any time
+which is particularly useful when doing long assignments that take many iterations to finish.
diff --git a/Wiki/home.md b/Wiki/home.md
index 0f1eee9..cc7e0cc 100644
--- a/Wiki/home.md
+++ b/Wiki/home.md
@@ -6,4 +6,8 @@ In this wiki you will find the documentation related to the `dojo` CLI.
## Assignment documentation
-* [Assignment creation](CLI-assignment-creation)
\ No newline at end of file
+* [Assignment creation](CLI-assignment-creation)
+
+## Exercise documentation
+
+* [How to perform an exercise](CLI-exercise-perform)
--
GitLab