docs: update report for PDG deliverable

docs/src/SUMMARY.md

@@ -3,7 +3,14 @@
 - [Installation](./install.md)
 - [Why?](./why.md)
 - [Changelog](./CHANGELOG.md)
-- [Report](./report.md)
+- [PDG-Report](./report.md)
+	- [Project-description](./project-description.md)
+	- [Architecture](./architecture.md)
+	- [Mockups](./mockups.md)
+	- [Landing page](./landing-page.md)
+	- [Technical choice](./technical-choice.md)
+	- [Work process](./work-process.md)
+	- [Pipeline CI/CD](./pipeline-ci-cd.md)
 - [Features development](./features.md)
 - [Experience for teachers](./teachers.md)
 - [Development](./dev.md)

docs/src/architecture.md

@@ -0,0 +1,25 @@
+## Planned architecture
+![PLX-architecture.png](img/png/PLX-architecture.png)
+
+## File architecture
+```sh
+cppexos # exos repository, C++ as example here
+	course.toml # define your course info
+	skills.toml # define your skills info and order
+	structs # first skill
+		mega-dog # first exo in this skill
+		    exos.toml # exos definition in this skill
+		    dog.cpp
+	    unit-dog # second exo with unit tests in GoogleTest
+		    exos.toml
+		    dog.cpp
+	pointers # second skill
+	    on-functions # first exo in this skill with 3 files
+		    exos.toml
+		    libparse.c
+		    libparse.h
+		    main.cpp
+	    debug # second exo in this skill with one file
+		    exos.toml
+		    crash.cpp
+```

docs/src/exo (1).md

@@ -0,0 +1,27 @@
+## Dog struct
+Petit programme qui affiche le nom d'un chien et son nombre de pattes. Affiche une erreur si des arguments manquants.
+
+Example execution:
+```sh
+> ./dog Joe 5
+Le chien est Joe et a 5 pattes
+> ./dog 
+Erreur: arguments manquants
+```
+
+<details>
+<summary>Solution</summary>
+
+```c
+#include <iostream>
+using namespace std;
+
+int main(int argc, char *argv[]) {
+  if (argc < 3)
+    cout << "Erreur: arguments manquants" << endl;
+  else
+    cout << "Le chien est " << argv[1] << " et a " << argv[2] << " pattes"
+         << endl;
+}
+```
+

docs/src/landing-page.md

@@ -0,0 +1 @@
+![[landing_page.png]]

docs/src/mokups.md

@@ -0,0 +1,137 @@
+## Mockups
+## Case study with the classic experience
+Let's consider a typical coding exercise that David needs to resolve:  
+
+---
+
+#### Dog message
+Write a small program that displays this message built with the first 2 args. You don't need to check the second arg to be a number.
+
+Example execution:
+```sh
+> ./dog 
+Error: missing argument firstname and legs number
+> ./dog Joe 4
+The dog is Joe and has 4 legs
+```
+
+<details>
+<summary>Solution</summary>
+
+```c
+#include <stdio.h>
+
+int main(int argc, char **argv) {
+  if (argc < 3)
+    printf("Error: missing argument firstname and legs number");
+  else
+    printf("The dog is %s and has %s legs\n", argv[1], argv[2]);
+}
+```
+
+</details>
+
+---
+
+To solve this exercise, David first read the instruction, then open his IDE, manually create a `main.c` file, copy-paste the starter code, read the existing code and complete the parts that need to be developed. Once he believes the code is ready, David compiles it by opening a terminal in the IDE and typing `gcc dog main.c` — oops! it should have been `gcc -o dog main.c`
+
+```bash
+PS C:\Users\david\CLionProjects\dog> gcc dog main.c
+c:/program files/mingw64/bin/../lib/gcc/x86_64-w64-mingw32/12.2.0/../../../../x86_64-w64-mingw32/bin/ld.exe: cannot find dog: No such file or directory
+collect2.exe: error: ld returned 1 exit status
+PS C:\Users\david\CLionProjects\dog> gcc -o dog main.c
+PS C:\Users\david\CLionProjects\dog> ./dog Joe 4
+The dog is Joe and has legs
+```
+
+After this, David input the name and number of legs and compares the output manually to see if it matches the expected result. Opening the instruction again, he realizes that the number of legs is not displayed! He returns to the code, adds the age variable, recompiles, and runs the program again, entering the name and number of legs again. This time, is the output correct? Now David checks his code against the solution... Okay, he could have used `printf` instead of `puts()` twice to display the full name. Moving on to the next exercise, he searches for the instruction, and the cycle repeats...
+
+All these additional steps around writing the code may seem insignificant at first glance, but their accumulation results in considerable friction. Additionally, there will be very few manual executions, meaning limited opportunities to gauge progress and adjust the code accordingly, coupled with the mental burden of compiling and running the program manually.
+
+![classic-xp.opti.svg](img/svg/classic-xp.opti.svg)
+This workflow resume all different steps that David performs until he finish the exercise.
+
+## Case study with the PLX experience
+
+Let's consider a struct exercise that Alice needs to resolve:  
+
+---
+
+#### 2. Basic dog struct
+
+Write a basic dog structure with a name and legs number. Print given dog with first 2 args. If `-n` ask to define a new dog, and if `-s` show the size of the struct.
+
+<details>
+<summary>Solution</summary>
+
+```c
+#include <stdio.h>  
+#include <stdlib.h>  
+#include <string.h>  
+
+typedef struct {  
+   const char *firstname;  
+   short legs_number;  
+} Dog;  
+
+void printDog(Dog *dog) {  
+   printf("The dog is %s and has %d legs\n", dog->firstname, dog->legs_number);  
+}  
+
+int main(int argc, char *argv[]) {  
+
+   if (strcmp(argv[1], "-n") == 0) {  
+      printf("New dog\nName: ");  
+      printf("\nNumber of legs: ");  
+      Dog newDog = {.firstname = argv[2], .legs_number = atoi(argv[3])};  
+      printDog(&newDog);  
+   } else if (strcmp(argv[1], "-s") == 0) {  
+      printf("sizeof(Dog): %lu\n", sizeof(Dog));  
+   } else {  
+      Dog dog = {.firstname = argv[1], .legs_number = atoi(argv[2])};  
+      printDog(&dog);  
+   }  
+}
+```
+
+</details>
+
+---
+For running PLX, Alice needs to run `plx` in the correct folder that contains the exercises if there is no ".plxproject" file in the given top-level folder the app provides a warning message. 
+
+<!--TODO: Think about the subfolder opening issue. The app will ask again for a folder.-->
+
+![home.opti.svg](img/svg/home.opti.svg)
+
+Arrows on the picture illustrate the event. This is the home layout of the app PLX. There are three options on this page. First, press `r` to access the last exercise that still needs to be finished. When PLX starts an exercise, it will automatically open the IDE with the correct file and compile the file for the first time. Secondly, press `l` to access the listing of exercises, and lastly press `?` to show the command of the app. So, Alice use PLX for the first time then she press `l` and enter in the list view.
+
+![list-1.opti.svg](img/svg/list-1.opti.svg)
+
+On the list view, there are two columns: 
+-  the left one for the list of skills that doesn't change
+-  the right side for the list of exercises for the current skill (the list immediately changes when she selects another skill). 
+- Press `Enter` to go inside the skill and access the list of exercises and `Esc` to go back.
+
+![list-2.opti.svg](img/svg/list-2.opti.svg)
+
+The meaning of colours for exercises: green = done, orange = one test pass, and default colour = otherwise. To navigate in the list, use `k` for going up and `j` for going down.
+
+![preview-exo.opti.svg](img/svg/preview-exo.opti.svg)
+
+Press `Enter` to go to the exercise preview and `Esc` to go back to the exercise list. The preview exercise shows the instruction and the path of the main file, but doesn't run any build in the background to save resources. The preview is not another page, however the `j` and `k` shortcuts will continue to work and the preview will be adapted.
+
+![exo-1.opti.svg](img/svg/exo-1.opti.svg)
+
+Alice found the exercise she needs to resolve. Her IDE opened the C file corresponding to the exercise. The checks are green when they do not fail and red otherwise. The first failing check is automatically opened. To navigate and see details of the next checks use `Ctrl+d` down and `Ctrl+u` up. When Alice saves the exercise file on the IDE, PLX will automatically run compilation and checks, and update the results of the checks.
+
+![error.opti.svg](img/svg/error.opti.svg)
+
+Alice makes some changes in is code to resolve check 2 but when she saves is file, PLX run the compilation and give the compilation error.
+
+![exo-2.opti.svg](img/svg/exo-2.opti.svg)
+
+When all checks are green the exo is done and Alice has the options to press `s` to see the solution. Scrolling inside the solution is with `k` (up) and `j` (down).
+
+![plx-xp.opti.svg](img/svg/plx-xp.opti.svg)
+
+This workflow resume all different steps that Alice performs on PLX until she finish the exercise.

docs/src/pipeline-ci-cd.md

@@ -0,0 +1,37 @@
+### GitHub workflow
+1. We protect the main branch on the main repository to avoid pushing commits directly without any review. The 2 others repository (website + organisation profile) are not protected for ease of change.
+1. For each feature or change:
+  1. we create a new issue and assign it to the correct person
+  1. create a new branch,
+  1. try to follow the conventionnal commits standard for writing commit messages,
+  1. when done we send a PR.
+  1. The PR is automatically merged only after one review, and trivial changes that do not review can be merged by the PR creator.
+  1. Github is configured to block merging if CI jobs are failing.
+  1. We try to delete the branch when PR is merged.
+## CI/CD strategy
+Most of the release process should be automated, this is why we configured GitHub actions to run different jobs.
+
+### PR validation strategy
+1. On each PR (and when new commits arrive) and on push on main, `cargo build` and `cargo test` are run to make sure everything is working
+1. On each git tag, we will run a CI job to test, build and run `cargo publish` to release PLX on [crates.io](https://crates.io/crates/plx)
+
+todo: document release process
+todo: document other OS
+
+### Release strategy
+
+To release a new version of PLX, here are the manual steps:
+1. Create a new release branch
+1. Choose a new version number based following semantic version
+1. Modify the `CHANGELOG.md` to document changes since last release
+1. Modify the `Cargo.toml` with the chosen version
+1. Run `cargo build` to update the duplicated version number in `Cargo.lock`
+1. Push the changes
+1. Open and merge PR of this release branch (tests must pass so we cannot release code with compilation errors)
+
+The CI release job starts and detect a version change (version in `Cargo.toml` different from the latest git tag) so the release process start
+1. Create a new tag with the extracted version
+1. Create a new release on Github with a link to the `CHANGELOG.md`
+1. Run `cargo publish` to publish plx on `crates.io`
+
+The result is that running `cargo install plx` again will install the new version!

docs/src/project-description.md

@@ -0,0 +1,37 @@
+# Features
+We described a lot of details about the a better experience, problems of the current experience, but here is **a complete central list of features we need to develop** during PDG and some other ideas for later. Some of them will have a dedicated issue on GitHub, but this is easier to see the global picture and progress here.
+### Functionnal requirements
+| Feature                                                                              | Status | Description                                                                                                             |
+| ------------------------------------------------------------------------------------ | ------ | ----------------------------------------------------------------------------------------------------------------------- |
+| View the Home page                                                                   | TODO   |                                                                                                                         |
+| View the List page                                                                   | TODO   | With the list of skills and exos                                                                                        |
+| C++ exo build+execution, but without configuration and without build folder visible  | TODO   | Support compiling C++ in single or multi files via Xmake without config in a separated build directory                  |
+| Java exo build+execution, but without configuration and without build folder visible | TODO   | Support compiling Java in single or multi files with `javac`                                                            |
+| Exo creation with one main file or possibly more starting files                      | TODO   | Support a way to describe those metadata and indicate which files are relevant.                                         |
+| Definition of automated check verifying outputs                                      | TODO   |                                                                                                                         |
+| Run automated output checks on starting files                                        | TODO   | Run check, generate result and diff if it differs                                                                       |
+| Run automated output checks on solution files                                        | TODO   | Adapt the compilation to build the solution files instead, and do the same things, after having checked the base files. |
+| Execute a check on a given binary file                                                                   | TODO   | Check and display if exercices passed or failed                                                                         |
+| Show why checks are failing | TODO   | Show why exercice failed (diff output / solution)                                                                       |
+| Start of the app                                                                  | TODO   | It's possible to resume to the last exo or to the next logical one by pressing `r`. |
+| Preview of exos                                                                      | TODO   | When searching for an exercice to do -> a preview of the exo with the metadata but do not run compilation.                      |
+| Save and restore exos states                                                               | TODO   | Save exos states (done / not done / in progress) and restore it on subsequent app launches. Shows immediately the states in list with colors. Enable exo resuming.    |
+| Code Editor opening                                                                  | TODO   | Open code editor when launching or switch to another exercice, the editor is defined via `$EDITOR`                                                                             |
+| Provide integrated documentation                                                     | TODO   | Press `?`to get an integrated documentation of all the keybinds available                              |
+|                                                                                      |        |                                                                                                                         |
+
+<!--TODO: continue this list-->
+
+### Non functionnal requirements
+1. It should be easy to create new exos and maintain them, converting an existing C++ exo should take less than 2 minutes.
+1. The watcher should be performant: it should only watch files that could be modified by the student or teacher, it should take less than 100ms to see detect a change.
+1. PLX should be usable during exo creation too to make sure the checks are passing on
+1. Once an exo is opened, with one IDE window at right and the terminal with PLX at left, the students should not need to open or move other windows and should be able to only `Alt+Tab`. All the automable steps should be automated to focus on learning tasks (including build, build configuration, running, output diffing, manual entries in terminal, detecting when to run, showing solution, switching to next exo).
+1. Switching to next exo should take less than 10 seconds. After this time: the IDE should be opened with the new file, and PLX should show the new exo details.
+1. Trivial exo files shoud not need any build configuration, PLX should be able to guess how to build the target with available files.
+1. Cross-plateform comptability meaning that PLX should work on all linux, windows and MAC machines.
+1. PLX shoud be designed in a modular way that allows for any easy addition of the features.
+1. Compiling an exercice should take less than (10 seconds). 
+1. When saving a file, the compilation starts. If a compilation is already running when saving a file, it should kill the actual compilation and launch a new compilation.
+1. When launching the tests, if tests are already running they should be stopped and relaunched again.
+1. PLX must have a file watcher and file parser to be able to watch the edited file(s) and return it states. This is necessary to be able to flag the exercice (in progress, done, not started) and return errors descriptions or status (passed / failed) of the exercice.