Merge branch '75-prepare-docker-deployment-submodule' into 'dux'

  stage: format

  script:

    - find ./docs -type f -name "*.md" -exec sed -i 's/^---$/______________________________________________________________________/' {} +

    - poetry run mdformat README.md ./docs --check --number --wrap 100

    - poetry run mdformat README.md ./docs --check --number

    - find ./docs -type f -name "*.md" -exec sed -i 's/^______________________________________________________________________$/---/' {} +

build:

	path = definition-registry

	url = ../definition-registry

	branch = main

[submodule "docker-deployment"]

	path = docker-deployment

	url = ../docker-deployment

	branch = main

### Formatting

For consistently clean and formatted Markdown files, utilize the [format.sh script](#3-formatsh).

For consistently clean and formatted Markdown files, utilize the [format.sh script](#4-formatsh).

- **_Maintain one sentence per line._**

- Lines should ideally not exceed 100 characters (the formatter will automatically break them).

- Lines should ideally not exceed 100 characters (can be followed, but does not have to be strict, e.g. 105 chars is OK).

- Let the formatter handle the rest.

## Dependencies

For the convenient usage of documentation and its versioning the following scripts are present:

### 1. update-files.sh

### 1. update-submodules.sh

This script is responsible for downloading the correct versions of files that are drown from another

repositories:

- (example) `file name` - source repository path -> documentation path

- `README.md` - _/backend/definitions/_ -> _/docs/tech/architecture/definitions/_

- `CHANGELOG.md` - _/backend/definitions/_ -> _/docs/tech/architecture/definitions/_

- `openapi.yml` - _/backend/_ -> _/docs/tech/api/_

- `showcase-definition.zip` - _/definition-registry/_ -> _/files-from-repos/showcase-definition.zip_

- `introductory-definition.zip` - _/definition-registry/_ ->

    _/files-from-repos/intro-definition.zip_

This script is a prerequisite to the _update-files.sh_ (unless initiation and switching to correct

branches/tags of submodules is done manually). The _update-files.sh_ script then uses files from

this submodules.

The script takes argument `-v` (or verbose `--version`) followed by a version (in format: `vX.0.0`)

for which we want the files. If no argument is provided it pulls the newest files from every

repository.

of the tag. If no argument is provided it pulls the newest states for every submodule/repository.

#### Usage Examples

- We created the new branch for the new release from the main.

- Backend and Definitions repositories are ready and appropriate commits are tagged (or the latest

    commits contain the wanted content).

- We run the following script if Backend and Definition repositories contain the wanted tag (e.g.,

    v4.0.0):

- Backend, definitions-registry, and docker-deployment repositories are ready and appropriate

    commits are tagged (or the latest commits contain the wanted content).

- We run the following script if the repositories contain the wanted tag (e.g., v4.0.0):

    ```bash

    poetry run ./update-files.sh -v v4.0.0

    poetry run ./update-submodule.sh -v v4.0.0

    ```

- If the Backend and Definition repositories do not contain a tag, but we know that latest content

    is wanted, we simply run:

- If the repositories do not contain a tag, but we know that latest content is wanted, we simply

    run:

    ```bash

    poetry run ./update-files.sh

    poetry run ./update-submodule.sh

    ```

    This will use the newest commits/content from all repositories.

### 2. update-links.sh

- If you require different branch/tag for each repository, you can do it manually the following way:

    ```bash

    # initialize the submodules

    git submodule init

    git submodule update --remote

    ```

    then within each submodule repository:

    ```bash

    cd ./<repository-name>

    git fetch --tags # only if you want to use a tag

    git checkout main

    git checkout tags/<your-wanted-tag> # only if you want to use a tag and it exists

    git checkout <commit-hash> # alternatively if no tag is present use commit hash of wanted state

    ```

Then, if you have each repository in the wanted state, proceed to _update-files.sh_.

### 2. update-files.sh

This script is responsible for the downloading of files that are drown from another repositories.

It is expected that either _update-submodules.sh_ was used are manual submodule initiation was done.

The following files are pulled from other repositories:

- (example) `file name` - source repository path -> documentation path

- `README.md` - _/backend/definitions/_ -> _/docs/tech/architecture/definitions/_

- `CHANGELOG.md` - _/backend/definitions/_ -> _/docs/tech/architecture/definitions/_

- `openapi.yml` - _/backend/_ -> _/docs/tech/api/_

- `showcase-definition.zip` - _/definition-registry/_ -> _/files-from-repos/showcase-definition.zip_

- `introductory-definition.zip` - _/definition-registry/_ ->

    _/files-from-repos/intro-definition.zip_

### 3. update-links.sh

This script serves for correcting all links pointing to version specific files (mostly definitions

zip archives). It is a simple sed (stream editor) script for changing the urls/paths.

    ```

- We should see modified files by the script via diff.

### 3. format.sh

### 4. format.sh

This script formats all `.md` files according to the needs of the mkdocs site generator. If the code

was not formatted by this script the pipeline will probably fail!

    poetry install

    ```

2. _(If needed)_ Run the utilities scripts to update (or downgrade) files pulled from other

    repositories:

2. _(If needed)_ Run the [utilities scripts](#scripts) to update (or downgrade) files pulled from

    other repositories:

    ```bash

    # (substitute 'X' for actual version number, e.g. v3.0.0)

    poetry run ./update-files.sh -v vX.0.0

    poetry run ./update-submodules.sh -v vX.0.0

    poetry run ./update-files.sh

    # (substitute 'releaseName' for actual release name, e.g. dux)

    poetry run ./update-links.sh -n releaseName

To create a new page for the documentation of the newest release you need to follow these steps:

### 1. Detach from main

### 1. Update and detach from main

Use the [scripts](#scripts) to pull and rewrite the files that are used from other repositories.

Important note!\

When _detaching_ from _main_, the content of the release (the state of the main branch) should be

_revised_ and _checked_. If mistakes or discrepancies are found after detaching, it is needed to fix

them _both in the detached release branch and main_ (this can be done by following

[this guide](#3-apply-update-to-both-main-and-release-branch)). For this reason it is advised to

detach from the main branch _as late as possible_.

**Important note!** When _detaching_ from _main_, the content of the release (the state of the main

branch) should be _revised_ and _checked_. If mistakes or discrepancies are found after detaching,

it is needed to fix them _both in the detached release branch and main_ (this can be done by

following [this guide](#3-apply-update-to-both-main-and-release-branch)). For this reason it is

advised to detach from the main branch _as late as possible_.

Create a branch whose content will be used when publishing a new page of the new release.

#!/usr/bin/env bash

mdformat README.md ./docs --no-validate --number --wrap 100

mdformat README.md ./docs --no-validate --number

# the formatter replaces '---' with the '______...' but it is required to stay due to mkdocs yaml directives

find ./docs -type f -name "*.md" -exec sed -i 's/^______________________________________________________________________$/---/' {} +

#!/usr/bin/env bash

VERSION=""

while [[ "$#" -gt 0 ]]; do

  case $1 in

    -v|--version)

      VERSION=$2

      shift 2;;

    *)

      shift;;

  esac

done

# Initialize and update git submodules

git submodule init

git submodule update --remote

if [ -n "$VERSION" ]; then

    echo "Required version: $VERSION"

    echo "Pulling files for version: $VERSION"

    for repo in "backend" "definition-registry"; do

        if [ -d "./$repo" ]; then

            cd "./$repo"

            git fetch --tags &>/dev/null

            git checkout main &>/dev/null # Ensure we are on a valid branch before switching

            git checkout tags/$VERSION &>/dev/null

            cd ../  # Return to the main directory

        fi

    done

else

    echo "No version provided, using the NEWEST files."

fi

# # Check the status of the git submodules

git submodule status