Skip to content
Snippets Groups Projects
Commit 5e609346 authored by michael.minelli's avatar michael.minelli
Browse files

Merge branch 'documentation_update' into v2.2.0

parents 63394ac0 75c6d701
No related branches found
No related tags found
No related merge requests found
Pipeline #26650 passed
Stage: test
Hide whitespace changes
Inline Side-by-side
CHANGELOG.md
+ 3
− 5
View file @ 5e609346
......@@ -14,14 +14,12 @@
**⚠️ Deprecation:**
-->
## 2.2.0 (?)
## 2.2.0 (2023-10-16)
### ✨ Feature
- `results.json` file is now optional (if the teaching staff don't want to provide test details)
- If the file is not present or the `success` field is not present:
- The exercise will be considered as valid if the container exit code is 0
- The `results.json` file will be construct / completed with the container exit code
- If the file is present, the exercise will be considered as valid
- The exercise will be considered as valid if the container exit code is 0
- The `results.json` file will be construct / completed with the container exit code
- The `volume` argument of `dojo_assignment.json` is now optional (if the teaching staff don't want to provide `results.json` file or other files)
- Assignment run command added (to run the assignment locally)
......
Wiki/Tutorials/1-Assignment-creation.md
+ 72
− 17
View file @ 5e609346
......@@ -118,8 +118,11 @@ services:
dockerfile: Dockerfile
volumes:
- hello_world_volume:/result # <hello_world_volume> must be the same as below but
# the name may be arbitrary. This volume must be
# present in the dojo_assignment.json file under the field
# the name may be arbitrary. The volume is optional but
# you can provide it for show details of the execution like
# tests passed or not or simply any log file you think that
# can be useful for the students. If it's present, this volume
# must be present in the dojo_assignment.json file under the field
# "result": {
# "volume": "hello_world_volume",
# ...
......@@ -129,18 +132,25 @@ volumes:
```
In this file, we see the definition of a `hello_world_volume` this is an arbitrary name and can be changed but it
must be coherent in this file and in the `dojo_assignment.json` file (more on this later configuration file in [The dojo configuration file](#the-dojo-configuration-file)).
This volume is responsible of mounting `/result/` directory which will contain all
This (optional) volume is responsible of mounting `/result/` directory which will contain all
the output generated by our assignment (again the name can be changed). In particular
in this director e will be required to create a `dojo_assignment.json` file
in this director he will be required to create a `dojo_assignment.json` file
that contains at least if the assignment was successfully performed (more on that at the end of the [Creating the assignment files](#creating-the-assignment-files) section).
## The dojo configuration file
The `dojo_assignment.json` file contains the general configuration of the assignment.
The important configuration parameters are:
- the *immutable files* which are files that will be overwritten when the compilation pipeline is run (even if the student
modifies these files the modifications will not be taken into account),
- the *results* which is the volume corresponding to the `docker-compose.yml` file.
The configuration parameters are:
- the `dojoAssignmentVersion` which define the version of the dojo assignment file (actually only version 1 is available),
- the `version` of you assignment,
- the `immutable` field which are files or directories that will be overwritten when the compilation pipeline is run (even if the student
modifies these files the modifications will not be taken into account). Each immutable is defined by:
- `path` **(required)**: the path of the immutable file or directory,
- `description` _(optional)_: provides a description of the immutable for the students or Dojo interface,
- `isDirectory` _(optional)_: `true` if the immutable is a directory, `false` otherwise (default),
- the `results` which provide information to the Dojo for finding results of the execution. The *result* field is defined by:
- `container` **(required)**: the name of the service in the docker compose file that will be run (his dependencies will be run automatically). In our case it is `hello_world`,
- `volume` _(optional)_: this field (`hello_world_volume`) corresponds to the `volumes` field in the `docker-compose.yml` file.
In its default form `dojo_assignment.json` file contains
```json
......@@ -160,13 +170,8 @@ In its default form `dojo_assignment.json` file contains
}
}
```
Here we see only one immutable file which is the `Dockerfile` (the `isDirectory` field is `false` but it is possible to make
complete directories immutable) and we see that:
* the value of the `container` field (`hello_world`) corresponds to
the value of the `container_name` field in the `docker-compose.yml` file,
* the value of the `volume` field (`hello_world_volume`) corresponds to the `volumes` field in the `docker-compose.yml` file.
This file will be completed in [The immutable files](#the-immutable-files) sectino with the files of our assignment that will be
This file will be completed in [The immutable files](#the-immutable-files) section with the files of our assignment that will be
created in the [next section](#creating-the-assignment-files).
## Creating the assignment files
......@@ -250,21 +255,23 @@ if [ $? -eq 0 ]; then
if [ $? -ne 0 ]; then
echo "Output is wrong:";
cat result/diff_output.txt
exit(1);
else
echo "All tests were a complete success"
GLOBAL_SUCCESS=true
exit(0);
fi
else
echo "Execution failed";
exit(2);
fi
else
echo "Compilation failed."
exit(3);
fi
jq --null-input --arg success $GLOBAL_SUCCESS \
'{"success": $success | test("true")}' > /result/results.json
```
We use the exit code to say to Dojo if the exercise was a success (exit code `0`) or a failure (all other exit codes).
Here one can see the creation of two different files that are located in the `result` directory:
- `result/results.json`
- `result/diff_output.txt`
......@@ -273,6 +280,19 @@ The `results.json` is mandatory to be created and must at least contain the
assignment is a success or a failure. The other files present in the `result` folder
can be retrieved by the students.
In the result directory you can provide the optional `result.json` file that can contain more details about the tests:
```
successfulTests?: number;
failedTests?: number;
successfulTestsList?: Array<string>;
failedTestsList?: Array<string>;
```
- the `successfulTests` which provide the number of successfully passed tests,
- the `failedTests` which provide the number of failed tests,
- the `successfulTestsList` which provide the list (of string) of successfully passed tests,
- the `failedTestsList` which provide the list (of string) of failed tests,
To test if everything works according to plan, one can again use the command
```bash
$ docker compose run --build hello_world
......@@ -375,6 +395,39 @@ Pour ce faire, il faut modifier le fichier `src/function.c` sous la ligne
annotée avec `TODO`. Bonne chance!
```
## Validate the assignment
Now that the assignment is ready, we must validate it.
You can do it first locally with the command
```bash
$ dojo assignment check
```
```console
Please wait while we are checking requirements...
✔ Docker daemon is running
✔ All required files exists
Please wait while we are validating dojo_assignment.json file...
✔ dojo_assignment.json file schema is valid
✔ Immutable files are valid
Please wait while we are validating docker compose file...
✔ Docker compose file structure is valid
✔ Docker compose file content is valid
Please wait while we are validating dockerfiles...
✔ Docker compose file content is valid
Please wait while we are running the assignment...
✔ Docker Compose file run successfully
✔ Linked services logs acquired
✔ Containers stopped and removed
┏━━━━━━━━━━━━━━━━━ Results ━━━━━━━━━━━━━━━━━┓
┃ ┃
┃ Global result : ✅ Success ┃
┃ ┃
┃ The assignment is ready to be pushed. ┃
┃ ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
```
## Publish the work
Now that the assignment is ready, we must publish it. First add/commit/push all the
......@@ -394,7 +447,9 @@ c_hello_world/
└── Makefile
```
Then one must *publish* the assignment for the students to be able to perform to get the exercise.
A pipeline will be automatically run to check that the assignment is valid (the same as the previous state).
Wait for the successfully completion of this pipeline and then you are ready to publish the assignment with the command:
```bash
$ dojo assignment publish c_hello_world
```
......
Wiki/UserDocumentation/2-Assignment-creation.md
+ 1
− 1
View file @ 5e609346
......@@ -48,7 +48,7 @@ dojo assignment create
git clone ssh://git@ssh.hesge.ch:10572/dojo/assignment/unique_name.git
```
3. Modify the `unique_name` assignment as you want (modify the Dockerfile, docker-compose.yml files, add a readme, source code, compilation tools, etc.). Commit and push our work (soon™ more details will be provided on how to create assignment).
4. Once the assignment is done it must be published to be available to students:
4. Once the assignment is done and validated by the pipeline it must be published to be available to students:
```bash
dojo assignment publish unique_name
```
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment