Editorial changes to make site build work

docker/mkdocs/Dockerfile

@@ -1,14 +1,17 @@
-FROM registry.gitlab.com/clarin-eric/docker-alpine-base:2.3.3
-
-# Alpine package dependencies
-RUN apk add --no-cache \
-		'py3-pip=22.3.1-r1'
+FROM registry.gitlab.com/clarin-eric/docker-alpine-base:2.6.9
 
 # Install mkdocs
-RUN pip install wheel && \
-	pip install \
-		mkdocs \
-		mkdocs-material
+RUN apk add --no-cache 'py3-pip=23.3.1-r0' \
+	&& python3 -m venv /mkdocs \
+	&& . /mkdocs/bin/activate \
+	&& pip install wheel \
+	&& pip install mkdocs mkdocs-material
+
+RUN echo -e \
+	"#!/usr/bin/env bash\n" \
+	"source /mkdocs/bin/activate && mkdocs \"\$@\"" \
+	> /usr/local/bin/entrypoint.sh \
+	&& chmod +x /usr/local/bin/entrypoint.sh
 
-ENTRYPOINT [ "/usr/bin/mkdocs" ]
+ENTRYPOINT [ "/usr/local/bin/entrypoint.sh" ]
 CMD []

docs/general-guidelines/maintenance.md

@@ -0,0 +1,60 @@
+## Maintenance
+
+Project statuses
+
+-   Prototype
+-   Active development
+-   Maint
+-   Deprecated - deployed
+-   Deprecated - undeployed
+
+<table width="538" cellpadding="7" cellspacing="0" style="page-break-before: auto; page-break-after: auto"><colgroup><col width="48"> <col width="93"> <col width="86"> <col width="66"> <col width="173"></colgroup><tbody><tr valign="top"><td width="48" bgcolor="#c9daf8" style="background: #c9daf8; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; border: none; padding: 0in; background: transparent; page-break-after: auto">Label</p></td><td width="93" bgcolor="#c9daf8" style="background: #c9daf8; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; border: none; padding: 0in; background: transparent; page-break-after: auto">Development</p></td><td width="86" bgcolor="#c9daf8" style="background: #c9daf8; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; border: none; padding: 0in; background: transparent; page-break-after: auto">Maintenance</p></td><td width="66" bgcolor="#c9daf8" style="background: #c9daf8; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="orphans: 0; widows: 0">Deployed</p></td><td width="173" bgcolor="#c9daf8" style="background: #c9daf8; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="orphans: 0; widows: 0">Notes</p></td></tr><tr valign="top"><td width="48" height="34" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="orphans: 0; widows: 0">A</p></td><td width="93" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; border: none; padding: 0in; background: transparent; page-break-after: auto"><b>+</b></p></td><td width="86" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; border: none; padding: 0in; background: transparent; page-break-after: auto"><b>+</b></p></td><td width="66" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="orphans: 0; widows: 0">-</p></td><td width="173" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="orphans: 0; widows: 0">Prototyping to first RC</p></td></tr><tr valign="top"><td width="48" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="orphans: 0; widows: 0">B</p></td><td width="93" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; border: none; padding: 0in; background: transparent; page-break-after: auto"><b>+</b></p></td><td width="86" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; border: none; padding: 0in; background: transparent; page-break-after: auto"><b>+</b></p></td><td width="66" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="orphans: 0; widows: 0"><b>+</b></p></td><td width="173" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="orphans: 0; widows: 0; margin-bottom: 0in">Matur(ing), in use</p><p align="left" style="orphans: 0; widows: 0">At least one stable release</p></td></tr><tr valign="top"><td width="48" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="orphans: 0; widows: 0">C</p></td><td width="93" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; border: none; padding: 0in; background: transparent; page-break-after: auto">-</p></td><td width="86" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; border: none; padding: 0in; background: transparent; page-break-after: auto"><b>+</b></p></td><td width="66" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="orphans: 0; widows: 0"><b>+</b></p></td><td width="173" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="orphans: 0; widows: 0">Stable, feature frozen</p></td></tr><tr valign="top"><td width="48" bgcolor="#ff9900" style="background: #ff9900; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="orphans: 0; widows: 0">D</p></td><td width="93" bgcolor="#ff9900" style="background: #ff9900; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; border: none; padding: 0in; background: transparent; page-break-after: auto">-</p></td><td width="86" bgcolor="#ff9900" style="background: #ff9900; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; border: none; padding: 0in; background: transparent; page-break-after: auto">-</p></td><td width="66" bgcolor="#ff9900" style="background: #ff9900; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="orphans: 0; widows: 0"><b>+</b></p></td><td width="173" bgcolor="#ff9900" style="background: #ff9900; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; border: none; padding: 0in; background: transparent; page-break-after: auto">Abandoned, in use</p></td></tr><tr valign="top"><td width="48" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="orphans: 0; widows: 0">E</p></td><td width="93" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="orphans: 0; widows: 0">-</p></td><td width="86" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="orphans: 0; widows: 0">-</p></td><td width="66" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="orphans: 0; widows: 0">-</p></td><td width="173" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="orphans: 0; widows: 0">Dead</p></td></tr></tbody></table>
+
+Definitions
+
+-   Development
+    -   There is a development roadmap specific to the dev project
+    -   Has at least one responsible developer assigned
+-   Maintenance
+    -   Has at least one responsible maintainer assigned
+        -   Responsible for monitoring code base in terms of vulnerabilities, functional breakages
+        -   Responsible for addressing (at the very least) critical issues in the code base
+    -   Example activities covered
+        -   Dependency / base image updates
+        -   Implement required adaptations to new or changed context (OS, runtime, servlet container, ...)
+
+<table width="624" cellpadding="7" cellspacing="0" style="page-break-before: auto; page-break-after: auto"><colgroup><col width="41"> <col width="150"> <col width="389"></colgroup><tbody><tr valign="top"><td width="41" bgcolor="#cfe2f3" style="background: #cfe2f3; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; border: none; padding: 0in; background: transparent; page-break-after: auto">Status</p></td><td width="150" bgcolor="#cfe2f3" style="background: #cfe2f3; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; border: none; padding: 0in; background: transparent; page-break-after: auto"><br></p></td><td width="389" bgcolor="#cfe2f3" style="background: #cfe2f3; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; border: none; padding: 0in; background: transparent; page-break-after: auto">Project examples</p></td></tr><tr valign="top"><td width="41" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; border: none; padding: 0in; background: transparent; page-break-after: auto">A</p></td><td width="150" style="border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="orphans: 0; widows: 0">Prototyping - first RC</p></td><td width="389" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; margin-bottom: 0in; border: none; padding: 0in; background: transparent; page-break-after: auto">VCR JS widget</p><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; margin-bottom: 0in; border: none; padding: 0in; background: transparent; page-break-after: auto">VLO 5.0</p><p align="left" style="orphans: 0; widows: 0">DOG</p></td></tr><tr valign="top"><td width="41" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; border: none; padding: 0in; background: transparent; page-break-after: auto">B</p></td><td width="150" style="border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="orphans: 0; widows: 0">Matur(ing), in use</p></td><td width="389" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; margin-bottom: 0in; border: none; padding: 0in; background: transparent; page-break-after: auto">VLO</p><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; border: none; padding: 0in; background: transparent; page-break-after: auto">VCR</p></td></tr><tr valign="top"><td width="41" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; border: none; padding: 0in; background: transparent; page-break-after: auto">C</p></td><td width="150" style="border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="orphans: 0; widows: 0">Stable, feature frozen</p></td><td width="389" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; margin-bottom: 0in; border: none; padding: 0in; background: transparent; page-break-after: auto">Switchboard</p><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; margin-bottom: 0in; border: none; padding: 0in; background: transparent; page-break-after: auto">Component Registry</p><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; margin-bottom: 0in; border: none; padding: 0in; background: transparent; page-break-after: auto">Centre Registry</p><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; margin-bottom: 0in; border: none; padding: 0in; background: transparent; page-break-after: auto">OAI-PMH Harvester, viewer</p><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; border: none; padding: 0in; background: transparent; page-break-after: auto">RASA</p></td></tr><tr valign="top"><td width="41" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; border: none; padding: 0in; background: transparent; page-break-after: auto">D</p></td><td width="150" style="border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="orphans: 0; widows: 0">Abandoned, in use</p></td><td width="389" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; margin-bottom: 0in; border: none; padding: 0in; background: transparent; page-break-after: auto"><a href="https://github.com/clarin-eric/SAML-metadata-checker/">SAML-metadata-checker</a></p><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; border: none; padding: 0in; background: transparent; page-break-after: auto">earlier: FCS?</p></td></tr><tr valign="top"><td width="41" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; border: none; padding: 0in; background: transparent; page-break-after: auto">E</p></td><td width="150" style="border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="orphans: 0; widows: 0">Dead</p></td><td width="389" style="background: transparent; border: 1.00pt solid #000000; padding: 0.07in"><p align="left" style="page-break-inside: auto; orphans: 0; widows: 0; border: none; padding: 0in; background: transparent; page-break-after: auto"><a href="https://github.com/clarin-eric/clarin-horizon_drupal_theme">clarin-horizon_drupal_theme</a></p></td></tr></tbody></table>
+
+\[TODO: guidelines matrix for status X aspect\]
+
+Per project status:
+
+-   What drives releases?
+    -   A-B: roadmap
+    -   C: external factors, e.g. support for underlying technology, fixing of critical bugs and vulnerabilities
+    -   D-E: n/a
+-   Maintainer(s) - tasks and responsibilities
+    -   A-C MUST address critical security risks
+    -   CAN address other issues
+        -   enhancements and new functionality covered by developer role!
+    -   No maintainer (cat D, E) -> operational handbook
+        -   Possibility to (temporarily) address as C in short term
+        -   OR (temporarily) shut down
+-   Repository
+    -   Cat A-C: MUST be findable in Git repositories
+    -   D: SHOULD be in Git repository, MAY be in deprecated repository system
+    -   E: SHOULD be archived
+-   Issue reporting & tracking
+    -   A-B: known issues, envisioned features are documented in issue tracking system by developer/maintainer
+        -   may be for C as well but without commitment
+    -   A-B-C: maintainer will handle incoming issue reports via repository system
+    -   D-E: issue reporting is disabled
+-   Documentation
+    -   A: needs to have minimal documentation (needs to be defined) for development, deployment, testing purposes (up-to-date README file)
+    -   B-C: need to have up-to-date documentation both for development and operational purposes and end users; changelog
+    -   D-E: documentation needs to include statement about status of project
+-   Monitoring -> operational
+    -   B-C: needs permanent monitoring with alerting, log aggregation to ensure good health
+    -   D: included in general monitoring to ensure being alive
+
+