docs: extend docs for ci scripts

65c3b9de · mrodzis · e7757844 · 65c3b9de · 65c3b9de · 65c3b9de
Commit 65c3b9de authored Jun 10, 2021 by mrodzis 💪
--- a/.ci-scripts/gitlab-remove-old-artifacts.sh
+++ b/.ci-scripts/gitlab-remove-old-artifacts.sh
 #!/bin/bash

+# This script is resposible for determining which artifacts are too old to be
+# kept any longer. The artifacts are needed and preserved for having the
+# environments at hand any time.
 #
-# Some lines have been commented since they don't work properly at the moment.
+# Currently artifacts are kept for two weeks since this is our average sprint
+# duration.
+#
+# Some lines have been commented out since they don't work properly at the moment.
 # We left them in there as a basis in case we want to improve the performance
 # of the build process at a later stage.
 #

--- a/.ci-scripts/remove_entrypoint.sh
+++ b/.ci-scripts/remove_entrypoint.sh
 #!/bin/bash

+# This script remove any entry point given at src/index.template.html.
+# If an entry point is removed, src/index.template.html is committed again
+# to the repository which triggers a new pipeline. Here there variable
+# $CONTINUE_BUILD comes into play.
+# In order to avoid having to build the complete application although the
+# current pipeline will trigger a new one, $CONTINUE_BUILD is set to "false"
+# and prevents a complete build and deployment.
+
 FILE="src/index.template.html"

 if grep -q '"entrypoint": ""' "$FILE"; then 

--- a/.ci-scripts/set-404-page.sh
+++ b/.ci-scripts/set-404-page.sh
 #!/bin/bash

+# This script creates a basic 404 page for GitLab pages.
+# It comes into play when a build isn't continued due to the entry point being removed.
+# Since the removal of an entry point triggers a new pipeline, the respective GitLab page
+# will be created accordingly. The page created by this script serves as a placeholder until
+# the correct page has been created.
+
 echo "Create 404 page"
 mkdir public
 echo "<!DOCTYPE html><html><head><title>TIDO 404</title><meta charset='utf-8'></head><body>404: no build contents have been provided</body>" > public/404.html
--- a/.ci-scripts/set_entrypoint_ci.sh
+++ b/.ci-scripts/set_entrypoint_ci.sh
 #!/bin/bash

-# this script sets the entrypoint for TIDO
+# This script sets the entry point for TIDO's GitLab pages. They are not part of version
+# controlling.
 #
-# reason: if an entrypoint is provided, it will be compiled and integrated into the build
-# the build takes precedence and prevents the according config option to take effect
-# on the the other hand, the entrypoint is needed for the demo page to show data
-# https://subugoe.pages.gwdg.de/emo/Qviewer/develop/#/
+# Reason: If an entrypoint is provided, it will be compiled and integrated into the build.
+# Since we still want to have data at our hands when developing and for the official TIDO
+# link, the entry point has to be set without being present in the repository.


 echo CI_COMMIT_REF_NAME=${CI_COMMIT_REF_NAME}
@@ -23,7 +23,7 @@ case $CI_COMMIT_REF_NAME in
    echo "set entrypoint for testing"
    # TIDO is developed in the context of the Ahiqar project, therefore we use the Ahiqar data for
    # development purposes.
-    ENTRY_POINT=https://ahikar-test.sub.uni-goettingen.de/api/textapi/ahikar/arabic-karshuni/collection.json
+    ENTRY_POINT=https://ahikar-dev.sub.uni-goettingen.de/api/textapi/ahikar/arabic-karshuni/collection.json
    sed -ri 's|.*("entrypoint"\s*:).*$|\t\t\t\1 "'${ENTRY_POINT}'",|' src/index.template.html
    ;;
 esac

--- a/.ci-scripts/update-artifacts.sh
+++ b/.ci-scripts/update-artifacts.sh
 #!/bin/bash

+# This script takes the old artifacts containing the data needed for the environments and
+# adds the current branch's data to them.
+
 dist_dir=$(grep distDir quasar.conf.js | cut -d "'" -f2)
 project_id=10921

-# get the latest 'deploy' artifact which contains the former states/environments
+# get and extract the latest 'deploy' artifact which contains the former states/environments
 jobs=$(curl --header "PRIVATE-TOKEN: $API_TOKEN" "https://gitlab.gwdg.de/api/v4/projects/${project_id}/jobs?scope=success" | jq 'sort_by(.finished_at) | reverse')
 latest_deploy_job_id=$(echo $jobs | jq '.[] | select(.stage == "deploy").id' | sed -n 1p)
-
 curl --output old-artifact.zip --header "PRIVATE-TOKEN: $API_TOKEN" "https://gitlab.gwdg.de/api/v4/projects/10921/jobs/${latest_deploy_job_id}/artifacts"
-
-# add current data to artifact
 unzip -u old-artifact.zip

+# add current data to artifact. this only takes place if $CONTINUE_BUILD is set to 'true' or we are on a feature/bugfix/… branch.
+# the differentiation between the branches is necessary because $CONTINUE_BUILD is only set on 'main' and 'develop'.
 if [[ $CONTINUE_BUILD == "true" || ($CI_COMMIT_BRANCH != "main" && $CI_COMMIT_BRANCH != "develop") ]]; then
    mkdir -p public/{${CI_COMMIT_SHORT_SHA},${CI_COMMIT_REF_SLUG}}
    echo public/${CI_COMMIT_SHORT_SHA} public/${CI_COMMIT_REF_SLUG} | xargs -n 1 cp --remove-destination --recursive ${dist_dir}/*