From c64099dd8027b93c88c728599b59ec1dc2bf0473 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tom=C3=A1=C5=A1=20H=C3=A1jek?= <xhajek8@fi.muni.cz>
Date: Thu, 19 Sep 2024 16:42:31 +0200
Subject: [PATCH] * fix references
* fix links in CHANGELOG
* update path in tech_overview
* fix typo
* add upgrade example, fix link, fix typo
* add upgrade tutorial and changelog.md
---
docs/tech/architecture/definitions/upgrade.md | 39 +++++++++++++++++++
docs/tech/architecture/overview.md | 2 +-
docs/tech/tech_overview.md | 2 +-
mkdocs.yml | 5 ++-
utilities.sh | 3 +-
5 files changed, 47 insertions(+), 4 deletions(-)
create mode 100644 docs/tech/architecture/definitions/upgrade.md
diff --git a/docs/tech/architecture/definitions/upgrade.md b/docs/tech/architecture/definitions/upgrade.md
new file mode 100644
index 0000000..22d31c5
--- /dev/null
+++ b/docs/tech/architecture/definitions/upgrade.md
@@ -0,0 +1,39 @@
+# How to upgrade 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 behaviour of certain definition aspect rather than syntax change 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.8.0**
+* New version: **0.9.0**
+
+1. In the [CHANGELOG](CHANGELOG.md) in the section **0.9.0** the only change is removal of field `auto` in `injects.yml`.
+2. Open `injects.yml`. Remove field `auto` from every inject category.
+3. Save the file.
+4. Check the `injects.yml` against `injects.yml` structure in the [definition documentation](README.md).
+5. Create a new .zip archive and upload it to the IXP.
+6. The upload process will check the definition for errors.
+
+**You have successfully upgraded the definition version.**
diff --git a/docs/tech/architecture/overview.md b/docs/tech/architecture/overview.md
index bd6a19c..684bbd9 100644
--- a/docs/tech/architecture/overview.md
+++ b/docs/tech/architecture/overview.md
@@ -38,7 +38,7 @@ It is composed out of these parts:
* Exercise Definitions: The exercise definitions module stores templates and definitions for different types of exercises.
These definitions include details such as injects, emails and tools.
It also checks and ensures that definitions are correctly configured and set up.
- For a more in-depth explanation of definitions, please refer to [definitions architecture.](definitions.md)
+ For a more in-depth explanation of definitions, please refer to [definitions documentation](definitions/README.md).
* Running Exercise: This module manages the execution and runtime aspects of tabletop exercises, including tracking the progress of ongoing exercises and managing the flow of injects.
* Authentication: Handles user authentication and authorization, ensuring secure access to the platform's functionalities.
diff --git a/docs/tech/tech_overview.md b/docs/tech/tech_overview.md
index 0fcbfdb..7beacf5 100644
--- a/docs/tech/tech_overview.md
+++ b/docs/tech/tech_overview.md
@@ -34,7 +34,7 @@ Each part of this section is designed to help developers, system administrators,
This document gives a high-level overview of the architecture of the IXP,
describing the main components, their interactions, and the overall system design.
It includes diagrams and explanations to help you understand how the platform is structured and how the different parts work together.
-- [Definitions](architecture/definitions.md):
+- [Definitions](architecture/definitions/README.md):
A detailed description of the key components and concepts within the IXP.
This section serves as a glossary, helping you understand specific terms and their meanings in the context of the platform.
diff --git a/mkdocs.yml b/mkdocs.yml
index 5797577..8bcb381 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -16,7 +16,10 @@ nav:
- Installation: tech/installation.md
- System architecture:
- Overview: tech/architecture/overview.md
- - Definition documentation: tech/architecture/definitions.md
+ - Definition documentation:
+ - Overview: tech/architecture/definitions/README.md
+ - Upgrade definition: tech/architecture/definitions/upgrade.md
+ - CHANGELOG: tech/architecture/definitions/CHANGELOG.md
- Authorization and User Management: tech/security.md
- API Documentation:
- Overview: tech/api/overview.md
diff --git a/utilities.sh b/utilities.sh
index 8ff053b..b93e4eb 100755
--- a/utilities.sh
+++ b/utilities.sh
@@ -12,7 +12,8 @@ mkdir -p docs/tech
mkdir -p files-from-repos
# Copy files to the respective directories
-cp ./backend/definitions/README.md ./docs/tech/architecture/definitions.md
+cp ./backend/definitions/README.md ./docs/tech/architecture/definitions/README.md
+cp ./backend/definitions/CHANGELOG.md ./docs/tech/architecture/definitions/CHANGELOG.md
cp ./backend/openapi.yml ./docs/tech/api/openapi.yml
cp ./frontend/docker/nginx-deployment/README.md ./files-from-repos/nginx-README.md
cp ./showcase-definition/assets/definition.zip ./files-from-repos/showcase-definition.zip
--
GitLab