doc-dev: create directory for developer documentation

diff --git a/doc-dev/README.md b/doc-dev/README.md
new file mode 100644 (file)
index 0000000..1559f7c
--- /dev/null
+++ b/doc-dev/README.md
@@ -0,0 +1,5 @@
+# Knot Resolver developer documentation
+
+This directory contains documentation for Knot Resolver developers. It is in no
+way exhaustive, but may contain some useful information about non-obvious things
+about our sources and our CI/CD pipelines.

diff --git a/doc-dev/docs-gitlab-pages.md b/doc-dev/docs-gitlab-pages.md
new file mode 100644 (file)
index 0000000..739bf05
--- /dev/null
+++ b/doc-dev/docs-gitlab-pages.md
@@ -0,0 +1,50 @@
+# Knot Resolver documentation in GitLab Pages
+
+Since version 6.0 (but possibly at some point back-ported to older versions),
+the Knot Resolver documentation is generated by the GitLab CI/CD pipeline. This
+way we control the build environment as opposed to ReadTheDocs, which we have
+been using in the past.
+
+The relevant CI jobs can be found in the `docs` section of
+`.gitlab-ci.yml` in the project root directory (jobs `docs:build`,
+`docs:develop`, `docs:release`, etc.).
+
+To keep the advantages of having multiple versions of the docs available for
+users that cannot update to the latest Knot Resolver, we are leveraging multiple
+GitLab features, namely the ability of *Pages* to serve project artifacts
+([currently under-documented by GitLab, but mentioned](https://docs.gitlab.com/ee/ci/jobs/job_artifacts.html#browse-the-contents-of-the-artifacts-archive)),
+and *Environments* to automate the creation of links to said artifacts.
+
+A `docs:public` job is also in place to publish our desired version (probably
+the latest stable, but we can theoretically choose anything) of the docs
+directly at <https://knot.pages.nic.cz/knot-resolver>.
+
+
+## Automatic generation
+
+The `docs:build` job takes care of building the documentation from sources and
+exposing it as its artifacts, which are then inherited by subsequent jobs:
+
+* For each commit on a branch, the `docs:develop` job is executed to publish the
+  docs as a development version. This may be used by users who work with
+  nightlies, as well as the development team for making sure the docs look the
+  way they want them to. For each branch, an environment is created with the
+  name [`docs-develop/<branch_name>`](https://gitlab.nic.cz/knot/knot-resolver/-/environments/folders/docs-develop).
+* For each tag, the `docs:release` job is executed to publish the docs as a
+  release version. These go into environments named
+  [`docs-release/<tag_name>`](https://gitlab.nic.cz/knot/knot-resolver/-/environments/folders/docs-release).
+
+
+### Environment removal
+
+GitLab environments may be un-published using the `Stop` button on the
+[Environments screen](https://gitlab.nic.cz/knot/knot-resolver/-/environments).
+This will hide the environment away, but not delete it. Stopped environments can
+be found on the
+[Stopped environments tab](https://gitlab.nic.cz/knot/knot-resolver/-/environments?page=1&scope=stopped&search=),
+from which they may also be re-published or permanently deleted.
+
+Outdated artifacts get automatically deleted by GitLab, but in the case where
+the branch does not exist anymore, the environment will stay and the link will
+lead to nowhere. These need to be cleaned up manually at the moment, but an
+automated mechanism may be introduced later.