Commit de0e0034 authored by Tomáš Hájek's avatar Tomáš Hájek
Browse files

Merge branch '100-update-definition-upgrade-tutorial-for-enigma-release' into 'main' 

docs: Update upgrade tutorial to version 0.24.7

Closes #100

See merge request inject/inject-docs!180
parents 0e6a66b8 780d0f3e

docs/changelog.md

+1 −1
Original line number Diff line number Diff line
@@ -14,7 +14,7 @@ Most significant changes between the releases are listed below.** 
- If you are interested in the definition and platform compatibility, go here:

    [version compatibility](tech/version-compatibility.md)



______________________________________________________________________

---



## 4.0.1 (Frontend)

docs/tech/architecture/definitions/upgrade.md

+43 −116
Original line number Diff line number Diff line
@@ -32,156 +32,83 @@ If you want to upgrade the current definition to a new version, use the followin 


## Example:



- Current version: **0.18.1**

- Current version: **0.23.3**



- New version: **0.23.3**

- New version: **0.24.7**



- In the `config.yml` change the field `version` from 0.18.1 to 0.23.3.

- In the `config.yml` change the field `version` from 0.23.3 to 0.24.7.



### 0.18.1 to 0.19.0

### 0.23.3 to 0.24.0



1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current

    version, which is, in this case, **0.19.0**.

2. The change in common definitions is in the syntax of `activate_milestone`,

    `deactivate_milestone`, and `roles`, where simple strings are now fields which means list

    notation in square brackets, e.g., instead of

    `activate_milestone: X_final_milestone, X_intro_milestone` the syntax is as follows

    `activate_milestone: [ X_final_milestone, X_intro_milestone ]`. So go through all the

    definition files and add square brackets `[]` around milestones or roles in the mentioned

    fields.

3. Open `objectives.yml` all `tags` fields using the syntax as in the previous change, so instead of

    `tags: apply, consult`, the designer has to write it in square brackets like this

    `tags: [ apply, consult ]`.

4. In milestones, if you use feature activation of milestones based on interaction with files, then

    you have to open `milestones.yml` and add square brackets around files in `file_names`,

    similarly as in previous points.

5. Lastly, all the labels in `questionnaires.yml` are also lists now, so put them in square

    brackets, as in previous points.

6. Check all the edited files against the structure in the [definition documentation](README.md).



### 0.19.0 to 0.19.1

    version, which is, in this case, **0.24.0**.

2. The breaking change alters the behaviour of `final` milestones in a way that when such a milestone is reached,

    it stops the exercise (for synchronous exercises, all teams must reach it). This change does not alter

    the definition syntactically but can break exercises if allowed to be reached prematurely.

3. Check the usage of `final` milestones.

4. If the behaviour is as intended, skip the change.

5. Else, edit `final` milestones usage according to expected behaviour.

6. If not skipped, check all the edited files against the structure in the [definition documentation](README.md).



1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current

    version, which is, in this case, **0.19.1**.

2. The change lies in adding a new type of questionnaire, auto-free-form. The new feature does not

    alter the current definition syntax.

3. Skip the change.



### 0.19.1 to 0.20.0



1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current

    version, which is, in this case, **0.20.0**.

2. The change lies in removing the team visible milestones feature, so if you have used this

    feature, remove the `team_visible` fields from `milestones.yml`.

3. Check the `milestones.yml` against the `milestones.yml` structure in the

    [definition documentation](README.md).



### 0.20.0 to 0.20.1

### 0.24.0 to 0.24.1



1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current

    version, which is, in this case, **0.20.1**.

2. These two changes lie in adding new options for free-form and auto-free-form questionnaires, like

    limiting the input size and enabling custom text in tools buttons. These new features do not

    alter the current definition syntax.

    version, which is, in this case, **0.24.1**.

2. The change lies in adding a new optional field `delay` for questionnaires.

    The feature does not break syntax of the previous version of the definition.

3. Skip the change.



### 0.20.1 to 0.20.2

### 0.24.1 to 0.24.2



1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current

    version, which is, in this case, **0.20.2**.

2. The change lies in adding a new type of questionnaire, multiple-choice. The new feature does not

    alter the current definition syntax.

    version, which is, in this case, **0.24.2**.

2. The change lies in adding optional activation of the performance overlay after exercise is finished.

    The feature does not break syntax of the previous version of the definition.

3. Skip the change.



### 0.20.2 to 0.20.3

### 0.24.2 to 0.24.3



1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current

    version, which is, in this case, **0.20.3**.

2. The change lies in adding a scoring option for the exercises by assigning a `score` to

    milestones. The new feature does not alter the current definition syntax.

3. Skip the change.



### 0.20.3 to 0.21.0



1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current

    version, which is, in this case, **0.21.0**.

2. In the common definitions, the field `file_name` has been renamed to `attachments`, and the

    syntax has changed; the attachments are now a list, so they must be enclosed in square

    brackets.

3. So go through all the definition files, replace the `file_name` field with `attachments`, and

    enclose its content into square brackets, e.g. `file_name: file.pdf` to

    `attachments: [ file.pdf ]`.

    version, which is, in this case, **0.24.3**.

2. These changes lie in adding new fields to the `config.yml` to describe the definition.

    Except for `name`, these fields are optional.

3. Add `name` into the `config.yml`.

4. Check all the edited files against the structure in the [definition documentation](README.md).



### 0.21.0 to 0.22.0

### 0.24.3 to 0.24.4



1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current

    version, which is, in this case, **0.22.0**.

2. The changes lie in adding the `instructor_notes` field to `config.yml` and adding the possibility

    of making the overlay endless. These new features do not alter the current definition syntax.

    version, which is, in this case, **0.24.4**.

2. The change lies in allowing empty answers in the free-form questions in the questionnaire.

    The feature does not break syntax of the previous version of the definition.

3. Skip the change.



### 0.22.0 to 0.22.1

### 0.24.4 to 0.24.5



1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current

    version, which is, in this case, **0.22.1**.

2. The change lies in adding a signing feature to the emails. The new feature does not alter the

    current definition syntax.

    version, which is, in this case, **0.24.5**.

2. The change lies in adding an option to specify a whitelist for file types uploaded during the exercise.

    This feature also comes with a default whitelist.

    Please verify that the whitelist is sufficient.

    If **not**, follow the documentation instructions; if **yes**, then proceed.

3. Skip the change.



### 0.22.1 to 0.22.2

### 0.24.5 to 0.24.6



1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current

    version, which is, in this case, **0.22.2**.

2. The change lies in adding optional internal file storage for trainees; the designers can put

    various files like incident handling manuals there for trainees to use during the exercise. The

    new feature does not alter the current definition syntax.

    version, which is, in this case, **0.24.6**.

2. The change lies in adding multiple new fields in common definitions, which serve for LLM features.

    The feature does not break syntax of the previous version of the definition.

3. Skip the change.



### 0.22.2 to 0.22.3

### 0.24.6 to 0.24.7



1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current

    version, which is, in this case, **0.22.3**.

2. The change lies in enabling questionnaires to be submitted after the exercise is over or after it

    has been stopped. The new feature does not alter the current definition syntax.

    version, which is, in this case, **0.24.7**.

2. The change adds a feature allowing explicit feedback on questionnaire correctness.

    The feature does not break syntax of the previous version of the definition.

3. Skip the change.



### 0.22.3 to 0.23.0



1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current

    version, which is, in this case, **0.23.0**.

2. Multiple optional `display_name` fields were added in the definition. These fields do not change

    the syntax of the definition and could be skipped.

3. The only vital change is in the `questionnaires.yml`. The title has been renamed, and the new

    required field `name` was added.

4. To upgrade questionnaires, rename the field `title` to `name` in every questionnaire to preserve

    current behavior.

5. Check the `questionnaires.yml` against the `questionnaires.yml` structure in the

    [definition documentation](README.md).



### 0.23.0 to 0.23.1



1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current

    version, which is, in this case, **0.23.1**.

2. The change lies in adding optional fields to learning activities in `objectives.yml`. The new

    feature does not alter the current definition syntax.

3. Skip the change.



### 0.23.1 to 0.23.2



1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current

    version, which is, in this case, **0.23.2**.

2. The change lies in adding a new feature to questionnaires; the questionnaires can now be

    repeatable. The new feature does not alter the current definition syntax.

3. Skip the change.



### 0.23.2 to 0.23.3



1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current

    version, which is, in this case, **0.23.3**.

2. There is no change, only removing the unintended limit for the number of correct answers in the

    multiple-choice questionnaires.



!!! NOTE



    The validation process does not allow fields other than those mentioned in