From 504d31283313c984302e89dae9ead3d17ea5b963 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1=C5=A1=20H=C3=A1jek?= <xhajek8@fi.muni.cz> Date: Fri, 20 Dec 2024 21:04:16 +0100 Subject: [PATCH] * fix typo * add missing information * update the upgrade tutorial from version 0.12.1 to 0.17.0 --- docs/tech/architecture/definitions/upgrade.md | 84 +++++++++++-------- 1 file changed, 51 insertions(+), 33 deletions(-) diff --git a/docs/tech/architecture/definitions/upgrade.md b/docs/tech/architecture/definitions/upgrade.md index c59a939..0faafe1 100644 --- a/docs/tech/architecture/definitions/upgrade.md +++ b/docs/tech/architecture/definitions/upgrade.md @@ -1,4 +1,4 @@ -# How to upgrade definition version? +# How to upgrade the definition version? If you want to upgrade the current definition to a new version, use the following [CHANGELOG](CHANGELOG.md). @@ -16,7 +16,7 @@ If you want to upgrade the current definition to a new version, use the followin 6. Each version contains information about changes and a structured description of affected files and their arguments. -7. Note that not every change is reflected in the files, some changes are only concerned with the behaviour of certain definition aspect rather than syntax change in the YAML files. +7. Note that not every change is reflected in the files; some changes are only concerned with the behavior of certain definition aspects rather than syntax changes in the YAML files. 8. Lastly, check the new version against [definition documentation](README.md) to see if the arguments in the files are the same. @@ -26,46 +26,64 @@ If you want to upgrade the current definition to a new version, use the followin ## Example: -* Current version: **0.8.0** -* New version: **0.12.1** +* Current version: **0.12.1** +* New version: **0.17.0** -* In the `config.yml` change the field `version` from 0.8.0 to 0.12.1. +* In the `config.yml` change the field `version` from 0.12.1 to 0.17.0. -### 0.8.0 to 0.9.0 -1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current definition version, which is, in this case, **0.9.0**. -2. removing the field `auto` in `injects.yml` is the only change. -3. Open `injects.yml`. Remove the field `auto` from every inject category. +### 0.12.1 to 0.13.0 +1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current version, which is, in this case, **0.13.0**. +2. The only change is transforming the `control` field into `controls` in `questionnaires.yml` in questions. +3. Open `questionnaires.yml`. If the `control` field is present, change it to `controls` in every question. +4. The change enhances the control options, as shown in the [definition documentation](README.md). To keep the functionality the same, prepend the previous control with the number of correct answer with the colon, e.g. correct answer is 1, prepend `1: ` +5. Save the file. +6. Check the `questionnaires.yml` against the `questionnaires.yml` structure in the [definition documentation](README.md). + +### 0.13.0 to 0.14.0 +1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current version, which is, in this case, **0.14.0**. +2. The only change is allowing more `info` type channels. +3. Open `injects.yml` and add to every info type inject field `target` with the name of the current info type channel specified in `channels.yml`. 4. Save the file. 5. Check the `injects.yml` against the `injects.yml` structure in the [definition documentation](README.md). -### 0.9.0 to 0.9.1 -1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current definition version, which is, in this case, **0.9.1**. -2. The only change is the addition of the optional field `initial_state` to milestones. Because the field is optional and the change indicates a new feature, it won't affect the functionality of your definition. +### 0.14.0 to 0.15.0 +1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current version, which is, in this case, **0.15.0**. +2. The change lies in adding a new type of questionnaire, free-form. The new feature does not alter the current definition syntax. 3. Skip the change. -### 0.9.1 to 0.10.0 -1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current definition version, which is, in this case, **0.10.0**. -2. The change lies in the changing behavior of specific injects that do not contain a `content` field. This is, again, a change of behavior that does not affect the current definition. +### 0.15.0 to 0.15.1 +1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current version, which is, in this case, **0.15.1**. +2. The change lies in the addition of confirmation buttons to injects. It is only a new feature that does not alter the current definition syntax. 3. Skip the change. -### 0.10.0 to 0.11.0 -1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current definition version, which is, in this case, **0.11.0**. -2. The change lies in changing the behavior of `delay` in `injects.yml`. If the definition uses **delay** functionality, this could change the desired behavior of the current definition. -3. The designer has to test if the exercise behaves as expected. -4. If it does, then skip the change. If it does not, then change the design of the affected part. - -### 0.11.0 to 0.12.0 -1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current definition version, which is, in this case, **0.12.0**. -2. The change is replacing the `text` field in `questionnaires.yml` for more generic `content` as described in [Overview](README.md). -3. Check the `content` structure in the [definition documentation](README.md). -4. Change every `text` field in `questionnaires.yml` for `content`. -5. Save the file. -6. Check the `questionnaires.yml` against the `questionnaires.yml` structure in the [definition documentation](README.md). - -### 0.12.0 to 0.12.1 -1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current version, which is, in this case, **0.12.1**. -2. The change lies in adding and enabling functionality for role-based exercises. Therefore, no change is needed. -3. Skip the change. +### 0.15.1 to 0.15.2 +1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current version, which is, in this case, **0.15.2**. +2. The change contains adding the field `description` to `config.yml`, `objectives.yml`, `channels.yml`, `milestones.yml`, `roles.yml` and `questionnaires.yml`. As seen in the [definition documentation](README.md), the fields are optional, so it is up to the designers to include more information in the definition. +3. Another change is addition of filed `display_name` to `channels.yml`, `milestones.yml` and `roles.yml`. Again, this new field is set to the previously set name, meaning the designer chooses to improve the definition. +4. Check the affected files against the structure in the [definition documentation](README.md). + +### 0.15.2 to 0.16.0 +1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current version, which is, in this case, **0.16.0**. +2. First, optional fields `target_audience` and `prerequisites` are added to the `config.yml`. The designer can choose to add this information. +3. Next, the `subject` field is added to the email templates in the `emails.yml`. Add the field `subject` to every email template with a meaningful subject. +4. Save the files. +5. Check the `emails.yml` against the `emails.yml` structure in the [definition documentation](README.md). +6. Check the `config.yml` against the `config.yml` structure in the [definition documentation](README.md). +7. The significant change lies in changing how the learning activities are bound together with milestones. Now the milestones are written to the `objectives.yml` instead of activities being written to the `milestones.yml`. +8. Add field `milestones` to every activity, with the name of the milestones previously bearing the name of the activity. +9. After connecting all activities with milestones, open `milestones.yml` and remove every field `activity`. +10. Check the `milestones.yml` against the `milestones.yml` structure in the [definition documentation](README.md). +11. Check the `objectives.yml` against the `objectives.yml` structure in the [definition documentation](README.md). + +### 0.16.0 to 0.17.0 +1. In the [CHANGELOG](CHANGELOG.md), find the first subsequent definition version to the current version, which is, in this case, **0.17.0**. +2. The change lies in adding the field `category` to `tools.yml`. If you previously used a category in `tools.yml` with the notation **category_toolName**, it is now mandatory to write the category in a separate field. +3. Add the field `category` to every tool with a category, remove the category from the name, and write it to the new field. +4. The next change is removing the field `description` from `questionnaires.yml`. Open `questionnaires.yml` and remove the field description from every questionnaire. +5. The last change is adding the new field `content` to the `questionnaires.yml`. The change allows for more information to be embedded in questionnaires. You can skip this change. +6. Save the files. +7. Check the `tools.yml` against the `tools.yml` structure in the [definition documentation](README.md). +8. Check the `questionnaires.yml` against the `questionnaires.yml` structure in the [definition documentation](README.md). * Create a new .zip archive and upload it to the IXP. * The upload process will check the definition for errors. -- GitLab