# How to upgrade the definition version?

If you want to upgrade the current definition to a new version, use the following
[CHANGELOG](CHANGELOG.md).

## How to proceed:

1. Take your current definition, and in `config.yml`, check the version.

2. Change the version in `config.yml` to a new version.

3. Use the [CHANGELOG](CHANGELOG.md) and start making changes step by step from your current
    version to the newest version that is compatible with IXP.

4. Make one single change at a time.

5. Be sure to make the change for all the concerning files and their attributes before proceeding
    with the following change.

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
    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.

9. Zip the definition and upload it to the IXP for the last validation.

10. **Done.** Enjoy your upgraded version!

## Example:

- Current version: **0.18.1**

- New version: **0.23.3**

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

### 0.18.1 to 0.19.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

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

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.
3. Skip the change.

### 0.20.1 to 0.20.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.
3. Skip the change.

### 0.20.2 to 0.20.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 ]`.
4. Check all the edited files against the structure in the [definition documentation](README.md).

### 0.21.0 to 0.22.0

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.
3. Skip the change.

### 0.22.0 to 0.22.1

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.
3. Skip the change.

### 0.22.1 to 0.22.2

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.
3. Skip the change.

### 0.22.2 to 0.22.3

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.
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
    [definition documentation](README.md). Before proceeding, please check that no definition file has
    extra fields. If it has, remove it, or the validation will fail.

- Create a new .zip archive and upload it to the IXP.
- The upload process will check the definition for errors.

**You have successfully upgraded the definition version.**
