Skip to content
Snippets Groups Projects

Adds a first version of the wiki documentation

Merged Adds a first version of the wiki documentation
add_wiki_doc into main
Merged orestis.malaspin requested to merge add_wiki_doc into main
Viewing commit 8979e9db
Show latest version
2 files
+ 159
− 1
Compare changes
  • Side-by-side
  • Inline
Files
2
Wiki/CLI-exercise-perform.md 0 → 100644
+ 154
− 0
 
# 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.
 
![The Gitlab CI pipeline succeeded!](pipeline.png)
 
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.