Add more details to docs/VERSIONING.md

docs/VERSIONING.md

@@ -1,5 +1,56 @@
-# Summary
+# DiracX Package Documentation
 
+## Overview
+
+DiracX is a comprehensive Python package, composed of several interconnected submodules. It's designed to provide robust and versatile functionalities, primarily through these key components:
+
+1. **User-Facing Components**:
+   - **`diracx`**: This is the primary interface for users, integrating both the Command Line Interface (CLI) and Python API.
+   - **`diracx-routers`**: Serves as the server component, offering HTTPS endpoints.
+   - **`diracx-tasks`**: Handles operations executed by DiracX servers, either periodically or upon request.
+
+2. **Containerization**:
+   - Each component is available as a container image, packaging DiracX along with all necessary dependencies.
+
+## Python Modules
+
+DiracX is structured into various modules, each serving a distinct purpose:
+
+- **`diracx-core`**: The foundational code base, utilized by all other DiracX modules.
+- **`diracx-db`**: Focuses on database functionalities.
+- **`diracx-routers`**: Implements a FastAPI application.
+- **`diracx-client`**: A client auto-generated from the OpenAPI specification in `diracx-routers`.
+- **`diracx-api`**: Provides higher-level operations building on `diracx-client`.
+- **`diracx-cli`**: The command line interface (`dirac`).
+- **`diracx`**: A metapackage offering `diracx-client`, `diracx-api`, and `diracx-cli`.
+
+These modules are each implemented as a [native Python namespace package](https://packaging.python.org/en/latest/guides/packaging-namespace-packages/).
+
+### Versioning Strategy
+
+- Currently, we employ a versioning format of v0.<major>.<minor>.
+- We only support using the same version across all `diracx-*` packages.
+- The client and server versions can vary, but the client version is always communicated to the server. Incompatibly old client versions may lead to request rejections, prompting a client update.
+
+## Container Images
+
+DiracX utilizes a structured approach to containerization:
+
+1. **Base Image**:
+   - All container images start from `diracx/base`.
+
+2. **Specialized Base Images**:
+   - `diracx/services-base`
+   - `diracx/tasks-base`
+   - `diracx/client-base`
+
+3. **Image Versioning and Building**:
+   - Images are built periodically (e.g., every Monday) and tagged as `YYYY.MM.DD.P`.
+   - A DiracX release triggers the creation of new `DiracXService`, `diracx/tasks`, and `diracx/client` images, based on specific `diracx/base` tags.
+   - This approach ensures stability in production environments.
+   - For testing purposes, the `latest` base images are used, with dependencies installed via `pip install`.
+
+See this diagram for an example of how this looks in practice:
 
 ```
                        ┌──────────────────────────┐
@@ -16,32 +67,15 @@
 
 ```
 
+### Dependencies
 
-# Dependencies
-
-
-duplication between setup.cfg and environment.yaml
-
-diracx/base: Dockerfile with environment.yml (basically python version)
-diracx/services-base: diracx/base Image + Dockerfile + environment.yml (fastapi +
-whatever service needs)
-diracx/services image: diracx/service-base + Dockerfile + pip install --no-dependencies diracx-service
-diracx/tasks-base image: diracx/base Image + Dockerfile + environment.yml (gfal2 + htcondor + whatever tasks needs)
-diracx/tasks image: diracx/tasks-base + Dockerfile + pip install --no-dependencies diracx-tasks
-
-
-
-# Image versioning
-
-diracx/base, diracx/service-base and diracx/tasks-base are versionned by date and regenerated every Monday. The ``latest`` tag moves along.
-
-A DiracX release results in the creation of new DiracXService and diracx/tasks images, base on  **specific** diracx/base tags (not ``latest``), which is the latest at this point in time
-
-This way, we are sure that whatever run in production is stable.
-
-As for the DiracX tests, they can start from the ``latest`` base images, and do `pip install` with allowed dependencies
-
+- There is a noted duplication between `setup.cfg` and `environment.yaml`.
+- The `diracx/base` image is built from a Dockerfile with `environment.yml`, primarily defining the Python version.
+- The `diracx/services-base` and `diracx/tasks-base` images extend `diracx/base` with additional Dockerfiles and `environment.yml`, tailored to their specific needs.
+- The `diracx/services` and `diracx/tasks` images are further built upon their respective base images, adding necessary packages through `pip install --no-dependencies`.
 
-# DiracX versioning
+## Extensions
 
-It is too early to decide on a proper long term scheme, but for the forseable future (DIRAC is around), we will have v0.<major>.<minor>.
+- Extensions one or more of `diracx`, `diracx-routers`, `diracx-tasks` (e.g. `mydiracx`, `mydiracx-routers`, `mydiracx-tasks`).
+- Extensions provide a corresponding container image based a specific release of the corresponding DiracX image.
+- The DiracX helm chart can then be configured to override the image and start up command that is used.