diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1eec6bc9dafce1daa13ce9468a60655ce2c572e7..a4d0f582d4aa88849532df7fc7799d85b497d7dd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -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)
diff --git a/Wiki/Tutorials/1-Assignment-creation.md b/Wiki/Tutorials/1-Assignment-creation.md
index 16441292665f46c699b6d6fb419dd9129f430504..848d3b9e3f9be09a460bc3b69e7a55b47ad320d7 100644
--- a/Wiki/Tutorials/1-Assignment-creation.md
+++ b/Wiki/Tutorials/1-Assignment-creation.md
@@ -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
```
diff --git a/Wiki/UserDocumentation/2-Assignment-creation.md b/Wiki/UserDocumentation/2-Assignment-creation.md
index 15c7392aaaa51cc1a762e9c2e0600ecf4577ae1d..76d65404f7d920ce8312ebc5f39483ef5eb71624 100644
--- a/Wiki/UserDocumentation/2-Assignment-creation.md
+++ b/Wiki/UserDocumentation/2-Assignment-creation.md
@@ -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
```