readme/who

readme.md

@@ -1,20 +1,61 @@
 # Shell to Python Continuous Deployment
 
 Get a common set of Python CI & CD commands \
-from various contexts of CA, CI and OCI / OS.
+from various contexts of CA, DNS, CI and OS / OCI.
 
-## Features
+## Why
 
-* Certification Authority certificates
-  * [X] custom
-  * [X] known
-* Continuous Integration platforms
+Project workflows can occur in:
+* an online or offline context, dealing with custom CA & DNS servers
+* various Continuous Integration platforms, with different workflow syntaxes
+* specific Operating Systems, having different sets of commands and packages
+* specific containers for JavaScript based actions (ForgeJo, Gitea, GitHub)
+What if there was a unified way to do so?
+
+## How
+
+Picture it…
+
+### Group environment variables
+
+* numbered
+  * Certificate Authority armored certificates
+  * Domain Name System servers IP addresses
+* set group environment variables for
+  * ref names for deployment contexts of feature, staging & release
+  * alternate locations of
+    * Git repositories of this project & its parent framework
+    * Operating Systems & Software packages
+  * SSH key & hosts for deployments
+  * a standalone POSIX shell script payload
+
+### Workflow files
+
+* calling the POSIX shell script payload as their very first step
+* using a unified YAML syntax made of actions implemented in Python
+
+### Continous Integration & Deployment
+
+* configuring the Operating System container
+* installing Python system & virtual environments
+
+## What
+
+### Features
+
+Handle project workflows in a unified way:
+* whether the network infrastructure is
+  * [X] online
+  * [X] offline with custom
+    * [X] Certificate Authorities
+    * [X] Domain Name System servers
+* whatever the Continuous Integration platform
   * [X] ForgeJo
   * [X] Gitea
   * [X] GitHub
   * [X] GitLab
   * [ ] SourceHut
-* Operating Systems
+* whatever the Operating System container
   * [X] Alma
     * [X] 9
     * [X] 8
@@ -40,34 +81,35 @@ from various contexts of CA, CI and OCI / OS.
     * [X] Noble (24.04)
     * [ ] Jammy (22.04)
 
-## How
+### Environment variables
 
-| Variable            | Description               | Default                         |
-|:--------------------|:--------------------------|:--------------------------------|
-| SPCD_BRANCH_RELEASE | Release deployment branch | main                            |
-| SPCD_BRANCH_STAGING | Staging deployment branch | dev                             |
-| SPCD_BRANCH_FEATURE | Feature deployment branch | f                               |
-| SPCD_CA_n           | Numbered CA certificates  |                                 |
-| SPCD_CMD_SUM        | Command to check sums     | sha512sum                       |
-| SPCD_DNS_n          | Numbered name servers     | 9.9.9.9                         |
-| SPCD_GIT_MAIN       | Main Git repository       | spcd                            |
-| SPCD_GIT_ROOT       | Root Git repository       | rwx                             |
-| SPCD_SSH_HOSTS      | domain.tld ssh-type pub   |                                 |
-| SPCD_SSH_KEY        | SSH private key           |                                 |
-| SPCD_URL_ALMA       | Alma repository URL       | https://repo.almalinux.org      |
-| SPCD_URL_ALPINE     | Alpine repository URL     | https://dl-cdn.alpinelinux.org  |
-| SPCD_URL_ARCH       | Arch repository URL       | https://geo.mirror.pkgbuild.com |
-| SPCD_URL_DEBIAN     | Debian repository URL     | https://deb.debian.org          |
-| SPCD_URL_EPEL       | EPEL repository URL       | https://dl.fedoraproject.org    |
-| SPCD_URL_FEDORA     | Fedora repository URL     | https://rpmfind.net             |
-| SPCD_URL_OPENSUSE   | OpenSUSE repository URL   | https://download.opensuse.org   |
-| SPCD_URL_PYTHON     | Python repository URL     | https://pypi.org/simple         |
-| SPCD_URL_ROCKY      | Rocky repository URL      | https://dl.rockylinux.org       |
-| SPCD_URL_UBUNTU     | Ubuntu repository URL     | https://ubuntu.mirrors.ovh.net  |
+| Variable          | Description              | Default                         |
+|:------------------|:-------------------------|:--------------------------------|
+| SPCD_CA_n         | Numbered CA certificates |                                 |
+| SPCD_CMD_SUM      | Command to check sums    | sha512sum                       |
+| SPCD_DNS_n        | Numbered name servers    | 9.9.9.9                         |
+| SPCD_GIT_MAIN     | Main Git repository      | spcd                            |
+| SPCD_GIT_ROOT     | Root Git repository      | rwx                             |
+| SPCD_GIT_SHUNIT   | ShUnit Git repository    | shunit2                         |
+| SPCD_REF_FEATURE  | Feature deployment ref   | f                               |
+| SPCD_REF_RELEASE  | Release deployment ref   | main                            |
+| SPCD_REF_STAGING  | Staging deployment ref   | dev                             |
+| SPCD_SSH_HOSTS    | domain.tld ssh-type pub  |                                 |
+| SPCD_SSH_KEY      | SSH private key          |                                 |
+| SPCD_URL_ALMA     | Alma repository URL      | https://repo.almalinux.org      |
+| SPCD_URL_ALPINE   | Alpine repository URL    | https://dl-cdn.alpinelinux.org  |
+| SPCD_URL_ARCH     | Arch repository URL      | https://geo.mirror.pkgbuild.com |
+| SPCD_URL_DEBIAN   | Debian repository URL    | https://deb.debian.org          |
+| SPCD_URL_EPEL     | EPEL repository URL      | https://dl.fedoraproject.org    |
+| SPCD_URL_FEDORA   | Fedora repository URL    | https://rpmfind.net             |
+| SPCD_URL_OPENSUSE | OpenSUSE repository URL  | https://download.opensuse.org   |
+| SPCD_URL_PYTHON   | Python repository URL    | https://pypi.org/simple         |
+| SPCD_URL_ROCKY    | Rocky repository URL     | https://dl.rockylinux.org       |
+| SPCD_URL_UBUNTU   | Ubuntu repository URL    | https://ubuntu.mirrors.ovh.net  |
 
-## Packages
+### Operating Systems containers
 
-### Latest
+#### Latest
 
 | os | https | updt-ca | python | graphviz | plantuml | shellcheck | shunit | shfmt |
 |:----------------|---|---|------------:|------:|-----------:|------:|------:|-----:|
@@ -79,7 +121,7 @@ from various contexts of CA, CI and OCI / OS.
 | Ubuntu Noble    | ☐ | ☐ |        3.12 | u2.42 | u1.2020.2  | u0.9  | 2.1.8 | u3.8 |
 | Alma / Rocky 9  | ☑ | ☑ | 3.9  → 3.12 |  2.44 | e1.2024.6  | e0.8  |   git |      |
 
-### Previous
+#### Previous
 
 | os | https | updt-ca | python | graphviz | plantuml | shellcheck | shunit | shfmt |
 |:----------------|---|---|------------:|------:|-----------:|------:|------:|-----:|
@@ -88,28 +130,49 @@ from various contexts of CA, CI and OCI / OS.
 | OpenSUSE 15.5   | ☐ | ☑ | 3.6  → 3.11 |  2.48 |  1.2020.9  |  0.8  | 2.1.6 |  3.5 |
 | Alma / Rocky 8  | ☑ | ☑ | 3.6  → 3.12 |  2.40 | e1.2024.6  | e0.6  |   git |      |
 
-### Older Python
+#### Older Python
 
 | os | https | updt-ca | python | graphviz | plantuml | shellcheck | shunit | shfmt |
 |:----------------|---|---|------------:|------:|-----------:|------:|------:|-----:|
 | Ubuntu Jammy    | ☐ | ☐ |        3.10 | u2.42 | u1.2020.2  | u0.8  | 2.1.6 | u3.4 |
 | Debian Bullseye | ☐ | ☐ |        3.9  |  2.42 |  1.2020.2  |  0.7  | 2.1.6 |      |
 
-## Tasks
+## Who
+
+### By
+
+[Marc Beninca](https://marc.beninca.link).
+
+### For
+
+People feeling the need to aim for consistence in the CI & CD universe.
+
+## Where
+
+* [Discord](https://discord.com/channels/983145051985154108/1255894420092485652)
+* [IRC](ircs://irc.libera.chat/#spcd)
+* [Web](https://spcd.rwx.work)
+  * [Git](https://forge.rwx.work/rwx.work/spcd)
+  * [RSS](https://forge.rwx.work/rwx.work/spcd.rss)
+  * [Workflows](https://forge.rwx.work/rwx.work/spcd/actions)
+
+## When
+
+### First
 
 * try git repo url variable first for shunit
-* turn readme into documentation
 
-### sh
+### Shell
 
 * fit banner to text
 * review repositories handling for systems
   * opensuse
     * codecs repository
     * disable & enable https
+* write function to clone git repositories
 * write unit tests
 
-### sh → py
+### Shell → Python
 
 * check file & variable sums
 * install system packages
@@ -129,7 +192,7 @@ from various contexts of CA, CI and OCI / OS.
     * activate
 * relay environment module name
 
-### py
+### Python
 
 * check
   * .py
@@ -143,3 +206,7 @@ from various contexts of CA, CI and OCI / OS.
   * actions
   * includes
 * write unit tests
+
+### Later
+
+* turn readme into documentation

spcd.sh

@@ -8,6 +8,7 @@
 [ -n "${SPCD_DNS_1}" ] || SPCD_DNS_1="9.9.9.9"
 [ -n "${SPCD_GIT_MAIN}" ] || SPCD_GIT_MAIN="spcd"
 [ -n "${SPCD_GIT_ROOT}" ] || SPCD_GIT_ROOT="rwx"
+[ -n "${SPCD_GIT_SHUNIT}" ] || SPCD_GIT_SHUNIT="shunit2"
 [ -n "${SPCD_URL_PYTHON}" ] || SPCD_URL_PYTHON="https://pypi.org/simple"
 
 # main
@@ -714,12 +715,7 @@ spcd_install_python_modules() {
     spcd_ipm__target="${SPCD_PYTHON_VENV_PACKAGES}"
     echo "→ ${spcd_ipm__root}"
     for spcd_ipm__repository in "${SPCD_GIT_MAIN}" "${SPCD_GIT_ROOT}"; do
-        case "${spcd_ipm__repository}" in
-        http*) spcd_ipm__url="${spcd_ipm__repository}" ;;
-        */*) spcd_ipm__url="${SPCD_PROJECT_ROOT}/${spcd_ipm__repository}" ;;
-        *) spcd_ipm__url="\
-${SPCD_PROJECT_ROOT}/${SPCD_PROJECT_PATH}/${spcd_ipm__repository}" ;;
-        esac
+        spcd_ipm__url="$(spcd_get_git_url "${spcd_ipm__repository}")"
         spcd_ipm__name="$(basename "${spcd_ipm__url}")"
         spcd_split
         echo "\
@@ -886,6 +882,16 @@ spcd_error_os() {
     exit "${SPCD_ERROR_OS}"
 }
 
+spcd_get_git_url() {
+    if [ -n "${1}" ]; then
+        case "${1}" in
+        http*) echo "${1}" ;;
+        */*) echo "${SPCD_PROJECT_ROOT}/${1}" ;;
+        *) echo "${SPCD_PROJECT_ROOT}/${SPCD_PROJECT_PATH}/${1}" ;;
+        esac
+    fi
+}
+
 spcd_grep_os() {
     spcd_grep_os__variable="${1}"
     [ -n "${spcd_grep_os__variable}" ] &&