dls-deploy-tools 0.7__tar.gz → 0.8.0__tar.gz

{dls_deploy_tools-0.7 → dls_deploy_tools-0.8.0}/.copier-answers.yml

@@ -1,5 +1,5 @@
 # Changes here will be overwritten by Copier
-_commit: 5.0.2
+_commit: 5.1.0
 _src_path: gh:DiamondLightSource/python-copier-template
 author_email: martin.gaughran@diamond.ac.uk
 author_name: Martin Gaughran

{dls_deploy_tools-0.7 → dls_deploy_tools-0.8.0}/.devcontainer/devcontainer.json

@@ -39,7 +39,10 @@
                 "redhat.vscode-yaml",
                 "ryanluker.vscode-coverage-gutters",
                 "charliermarsh.ruff",
-                "ms-azuretools.vscode-docker"
+                "ms-azuretools.vscode-docker",
+                // Embedded HTML preview for built Sphinx docs (right-click
+                // build/html/index.html -> "Show Preview")
+                "ms-vscode.live-server"
             ]
         }
     },

{dls_deploy_tools-0.7 → dls_deploy_tools-0.8.0}/.github/CONTRIBUTING.md

@@ -24,4 +24,4 @@ It is recommended that developers use a [vscode devcontainer](https://code.visua
 
 This project was created using the [Diamond Light Source Copier Template](https://github.com/DiamondLightSource/python-copier-template) for Python projects.
 
-For more information on common tasks like setting up a developer environment, running the tests, and setting a pre-commit hook, see the template's [How-to guides](https://diamondlightsource.github.io/python-copier-template/5.0.2/how-to.html).
+For more information on common tasks like setting up a developer environment, running the tests, and setting a pre-commit hook, see the template's [How-to guides](https://diamondlightsource.github.io/python-copier-template/5.1.0/how-to.html).

{dls_deploy_tools-0.7 → dls_deploy_tools-0.8.0}/.github/workflows/ci.yml

@@ -18,8 +18,8 @@ jobs:
   test:
     strategy:
       matrix:
-        runs-on: [ "ubuntu-latest" ] # can add windows-latest, macos-latest
-        python-version: [ "3.12", "3.13", "3.14" ]
+        runs-on: ["ubuntu-latest"] # can add windows-latest, macos-latest
+        python-version: ["3.12", "3.13", "3.14"]
       fail-fast: false
     uses: ./.github/workflows/_test.yml
     with:

dls_deploy_tools-0.8.0/.markdownlint.yaml

@@ -0,0 +1,12 @@
+# Documentation line-length enforcement.
+#
+# An 88-character limit for documentation, matching [tool.ruff] line-length in
+# pyproject.toml. Only the line-length rule (MD013) is enabled.
+#
+# Files generated by the Copier template are excluded via the
+# markdownlint-cli2 hook in .pre-commit-config.yaml rather than reformatted.
+default: false
+MD013:
+  line_length: 88
+  tables: false # Markdown tables cannot be sensibly wrapped
+  code_blocks: false # fenced code and tree diagrams cannot be wrapped

{dls_deploy_tools-0.7 → dls_deploy_tools-0.8.0}/.pre-commit-config.yaml

@@ -31,6 +31,29 @@ repos:
         entry: uv sync
         files: ^(uv\.lock|pyproject\.toml)$
 
+      - id: generate-schema
+        name: regenerate JSON schemas from models
+        pass_filenames: false
+        language: system
+        entry: deploy-tools schema src/deploy_tools/models/schemas
+        files: ^src/deploy_tools/models/.*\.py$
+
+  - repo: https://github.com/DavidAnson/markdownlint-cli2
+    rev: v0.23.1
+    hooks:
+      - id: markdownlint-cli2
+        name: enforce 88-char line length in docs
+        files: ^docs/.*\.md$
+        # Files generated by the Copier template are excluded.
+        exclude: |
+          (?x)^docs/(
+            index|genindex|how-to|tutorials|explanations|reference|
+            how-to/contribute|how-to/run-container|tutorials/installation|
+            explanations/decisions|
+            explanations/decisions/0001-record-architecture-decisions|
+            explanations/decisions/0002-switched-to-python-copier-template
+          )\.md$
+
   - repo: https://github.com/gitleaks/gitleaks
     rev: v8.28.0
     hooks:

{dls_deploy_tools-0.7 → dls_deploy_tools-0.8.0}/.vscode/tasks.json

@@ -4,18 +4,15 @@
     "version": "2.0.0",
     "tasks": [
         {
+            "label": "Clean deployment",
             "type": "shell",
-            "label": "Tests, lint and docs",
-            "command": "tox -p",
-            "options": {
-                "cwd": "${workspaceRoot}"
-            },
-            "problemMatcher": [],
+            "command": "rm -rf ${workspaceFolder}/demo-output/ && mkdir ${workspaceFolder}/demo-output/",
+            "problemMatcher": []
         },
         {
-            "label": "Generate schema",
+            "label": "Validate deployment",
             "type": "shell",
-            "command": "deploy-tools schema ${input:schema-folder}",
+            "command": "deploy-tools validate ${input:allow-all} ${input:from-scratch} ${input:test-build} ${input:deploy-folder} ${input:config-folder}",
             "problemMatcher": []
         },
         {
@@ -25,27 +22,30 @@
             "problemMatcher": []
         },
         {
-            "label": "Clean deployment",
+            "label": "Compare deployment to snapshot",
             "type": "shell",
-            "command": "rm -rf ${workspaceFolder}/demo-output/ && mkdir ${workspaceFolder}/demo-output/",
+            "command": "deploy-tools compare ${input:compare-mode} ${input:deploy-folder}",
             "problemMatcher": []
         },
         {
-            "label": "Validate deployment",
+            "label": "Generate schema",
             "type": "shell",
-            "command": "deploy-tools validate ${input:allow-all} ${input:from-scratch} ${input:test-build} ${input:deploy-folder} ${input:config-folder}",
+            "command": "deploy-tools schema ${input:schema-folder}",
             "problemMatcher": []
         },
         {
-            "label": "Compare deployment to snapshot",
             "type": "shell",
-            "command": "deploy-tools compare ${input:compare-mode} ${input:deploy-folder}",
-            "problemMatcher": []
+            "label": "Recreate tests sample output from golden-master configuration",
+            "command": "tests/generate_samples.sh",
+            "options": {
+                "cwd": "${workspaceRoot}"
+            },
+            "problemMatcher": [],
         },
         {
             "type": "shell",
-            "label": "Recreate tests sample output from demo_configuration",
-            "command": "tests/generate_samples.sh",
+            "label": "Tests, lint and docs",
+            "command": "tox -p",
             "options": {
                 "cwd": "${workspaceRoot}"
             },

{dls_deploy_tools-0.7 → dls_deploy_tools-0.8.0}/Dockerfile

@@ -4,7 +4,7 @@ FROM ghcr.io/diamondlightsource/ubuntu-devcontainer:noble AS developer
 
 # Add any system dependencies for the developer/build environment here
 RUN apt-get update -y && apt-get install -y --no-install-recommends \
-    graphviz environment-modules wget \
+    graphviz environment-modules wget file \
     && cd /tmp \
     && wget https://github.com/apptainer/apptainer/releases/download/v1.3.3/apptainer_1.3.3_amd64.deb \
     && apt install -y ./apptainer_1.3.3_amd64.deb \
@@ -31,7 +31,7 @@ FROM ubuntu:noble AS runtime
 
 # Add apt-get system dependecies for runtime here if needed
 RUN apt-get update -y && apt-get install -y --no-install-recommends \
-    graphviz environment-modules wget git ca-certificates \
+    graphviz environment-modules wget git ca-certificates file \
     && update-ca-certificates \
     && cd /tmp \
     && wget https://github.com/apptainer/apptainer/releases/download/v1.3.3/apptainer_1.3.3_amd64.deb \

{dls_deploy_tools-0.7/src/dls_deploy_tools.egg-info → dls_deploy_tools-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dls-deploy-tools
-Version: 0.7
+Version: 0.8.0
 Summary: A set of tools used for deploying applications to a shared filesystem.
 Author-email: Martin Gaughran <martin.gaughran@diamond.ac.uk>
 License:                                  Apache License
@@ -210,6 +210,7 @@ Classifier: Development Status :: 3 - Alpha
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -235,8 +236,9 @@ access to a shared filesystem. We use the
 [Environment Modules](https://modules.readthedocs.io/en/latest/) package to make these
 applications available to the end user.
 
-Source          | <https://github.com/DiamondLightSource/deploy-tools>
+What            | Where
 :---:           | :---:
+Source          | <https://github.com/DiamondLightSource/deploy-tools>
 PyPI            | `pip install dls-deploy-tools`
 Docker          | `docker run ghcr.io/diamondlightsource/deploy-tools:latest`
 Documentation   | <https://diamondlightsource.github.io/deploy-tools>
@@ -246,93 +248,36 @@ The demo_configuration folder in this repository can be passed as the config_fol
 the deploy-tools commands. The deployment_root needs to be a writeable location for all
 files to get deployed under.
 
+These commands act on a shared deployment area, so we recommend running them from a CI
+pipeline gated by change review rather than by hand. Running them manually against the demo
+configuration, as below, is the quickest way to see what each does — the
+[documentation](https://diamondlightsource.github.io/deploy-tools) has a hands-on tutorial
+and a guide to driving them from CI.
+
+The examples below use the `deploy-tools` console script; `python -m deploy_tools` is
+equivalent if you prefer to invoke the module directly.
+
 ```
 deployment_root = /path/to/deployment/root
 config_folder = /path/to/config/folder
-schema_folder = /path/to/schema/folder
-
-# Generate the schema for configuration yaml files
-python -m deploy_tools schema $schema_folder
 
 # Validate the deployment configuration files, also ensuring that the required updates
 # are compatible with the previous deployments.
-python -m deploy_tools validate $deployment_root $config_folder
+deploy-tools validate $deployment_root $config_folder
 
 # Synchronise the deployment area with the configuration files. This will first run
 # validation as part of determining the required changes
-python -m deploy_tools sync $deployment_root $config_folder
-
-```
-
-## Deployment Steps
-
-There are several key steps that make up the deployment process. Note that these are a
-bit different to the CLI commands; see `deploy-tools --help` for more information.
-
-|**Step**|**Description**                                                                                                                                                                                                                                  |
-|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-|Compare |Compare the snapshot taken of the previous deployment with the modulefiles and built modules that already exist. This ensures that the Deployment Area is in a healthy state                                                                     |
-|Validate|Process the updated configuration. By comparing the new configuration files with a snapshot from the previous deployment, we determine the set of actions that need to be taken                                                                  |
-|Build   |Generate entrypoint scripts, configuration files and environment variables for a given Module. These are output to the Build Area                                                                                                                |
-|Deploy  |Move all built Modules from the Build Area into the Modules Area. A link to the built modulefile is moved to either the Modulefiles Folder or Deprecated Folder, depending on its deprecation status. Update default versions for the modulefiles|
-
-## JSON Schema
-
-A set of JSON schema files are provided under `src/deploy_tools/models/schemas`. These are generated from the Pydantic models in the schemas parent directory.
+deploy-tools sync $deployment_root $config_folder
 
-We strongly recommend that you provide a schema for configuration file validation. The relevant lines at the top of each release file are:
+# Compare the current deployment snapshot against what is actually deployed in the
+# deployment area. Run this before a deploy to confirm a healthy state.
+deploy-tools compare $deployment_root
 
-```# yaml-language-server: $schema=/workspaces/deploy-tools/src/deploy_tools/models/schemas/release.json```
-
-As the demo_configuration is used during development, we set it to use the locally generated schemas. Note that the 'Generate Schema' VSCode task will update the schemas according to any update of the code, but you need to trigger this manually and check the contents in.
-
-For any production configuration, you should set it to use schema files from GitHub.
-
-## CLI Commands, VSCode Tasks and Debug Configuration
-
-The following CLI commands are used in our CI/CD process to update the Deployment Area
-using new configuration.
-
-In order to help with development and testing, these commands (plus useful defaults) are
-available as Tasks and Debug configurations for VSCode. These tasks (plus their default
-inputs) should create a separate `demo-output` folder at the top-level of the workspace
-folder.
-
-You will need to use the `--from-scratch` argument if starting from a clean Deployment
-Area, as there is no snapshot from a prior Deploy step.
-
-It is recommended that you use `--help` to explore the commands, arguments and options
-in greater detail.
-
-|**Name**                      |**CLI command**           |**Description**                                                                                                                                                                                                     |
-|------------------------------|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-|Generate Schema               |`deploy-tools schema`     |Generate the yaml schema (in .json format) for the top-level configuration files                                                                                                                                    |
-|Clean deployment              |`rm -rf <Deployment Root>`|Wipe the deployment area local to your own checkout of deploy-tools, enabling you to test a deployment from scratch                                                                                                 |
-|Sync Modules                  |`deploy-tools sync`       |Synchronise the Deployment configuration with the Deployment Area                                                                                                                                                   |
-|Validate deployment           |`deploy-tools validate`   |Compare the new configuration with that previously used when deploying modules, and test the build process if requested                                                                                             |
-|Compare deployment to snapshot|`deploy-tools compare`    |Compare the configuration stored from the last `deploy-tools sync` run, with the state of any deployed Modules. This should always be run by CI/CD before attempting to Deploy, and any differences will be reported|
-
-## Glossary
-
-See the Deployment Steps above for an overview of the primary stages of a deployment.
+```
 
-|**Term**           |**Definition**                                                                                                                                                                                                                                                                                              |
-|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-|Environment Modules|A [standard package for Linux](https://modules.readthedocs.io/en/latest/) that provides definitions for loading and unloading 'Environment Modules'. Note that while we are using this system, our definition of Module is separate. If we are referring to an Environment Module, we will use the full name|
-|Modulefile         |Used by the Environment Modules package to specify all details of an Environment Module. This can include executables to add to the path, environment variables to set, etc.                                                                                                                                |
-|Deployment         |The sum total of all Releases (deprecated or not) that are to be maintained in the Deployment Area                                                                                                                                                                                                          |
-|Module             |A set of files that can be used to provide applications on your path, provide configuration, and set environment variables. We do this using the Environment Modules system by providing a Modulefile with the relevant configuration                                                                       |
-|Release (noun)     |A Module, including version, alongside its lifecycle (i.e. deprecation) status                                                                                                                                                                                                                              |
-|Application        |Each Module can be configured with multiple Applications, each one providing one or more executables. As of writing, there are 2 types of Application: `Apptainer` and `Shell` (Bash script)                                                                                                                |
-|Deployment Area    |The top-level location where all Modules are to be deployed. This is typically a shared filesystem location for general use by multiple people. Note that there are several subdirectories which are used by `deploy-tools` for different purposes                                                          |
-|(Area) Root        |Refers to the filesystem path at the root of the given Area.                                                                                                                                                                                                                                                |
-|Deployment Step    |Refers to one of the primary steps that make up the Deployment process. See the section 'Deployment Steps' above for a breakdown                                                                                                                                                                            |
-|Build Area         |The filesystem location used for building modules. This should ideally be on the same filesystem as the Deployment area to ensure that later move operations are atomic, so by default it is the `build` subdirectory of the Deployment Root. We use a different location when testing builds               |
-|Modules Area       |Refers to the `modules` folder under the Deployment Root. The final location for files built for a particular Module configuration                                                                                                                                                                          |
-|Modulefiles Folder |Refers to the `modulefiles` folder under the Deployment Root. When this path is added to the MODULEPATH environment variable, all modulefiles can then be accessed by the End User using the standard Environment Modules interface (`module avail`, etc.)                                                  |
-|Deprecate          |Moving a modulefile to the separate Deprecated Folder, to indicate that its use should be discouraged                                                                                                                                                                                                       |
-|Deprecated Folder  |The folder used to contain Modulefiles for Modules that have been deprecated. By adding the modulefiles subdirectory to your MODULEPATH environment variable, you then have the ability to use any deprecated Module as normal.                                                                             |
-|End User           |Refers to anybody who is intending to make use of a deployed Module. This can include the people modifying configuration themselves                                                                                                                                                                         |
+Generating the JSON schema files with `deploy-tools schema <folder>` is a separate,
+occasional task: it produces the schemas that editors use to validate configuration files,
+and is not part of a deployment. See the schema reference in the documentation.
 
 <!-- README only content. Anything below this line won't be included in index.md -->
 

dls_deploy_tools-0.8.0/README.md

@@ -0,0 +1,60 @@
+[![CI](https://github.com/DiamondLightSource/deploy-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/DiamondLightSource/deploy-tools/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/DiamondLightSource/deploy-tools/branch/main/graph/badge.svg)](https://codecov.io/gh/DiamondLightSource/deploy-tools)
+[![PyPI](https://img.shields.io/pypi/v/dls-deploy-tools.svg)](https://pypi.org/project/dls-deploy-tools)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
+
+# deploy_tools
+
+A set of tools used for deploying applications to a shared filesystem.
+
+This is used for deploying containerised desktop applications to many users who have
+access to a shared filesystem. We use the
+[Environment Modules](https://modules.readthedocs.io/en/latest/) package to make these
+applications available to the end user.
+
+What            | Where
+:---:           | :---:
+Source          | <https://github.com/DiamondLightSource/deploy-tools>
+PyPI            | `pip install dls-deploy-tools`
+Docker          | `docker run ghcr.io/diamondlightsource/deploy-tools:latest`
+Documentation   | <https://diamondlightsource.github.io/deploy-tools>
+Releases        | <https://github.com/DiamondLightSource/deploy-tools/releases>
+
+The demo_configuration folder in this repository can be passed as the config_folder to
+the deploy-tools commands. The deployment_root needs to be a writeable location for all
+files to get deployed under.
+
+These commands act on a shared deployment area, so we recommend running them from a CI
+pipeline gated by change review rather than by hand. Running them manually against the demo
+configuration, as below, is the quickest way to see what each does — the
+[documentation](https://diamondlightsource.github.io/deploy-tools) has a hands-on tutorial
+and a guide to driving them from CI.
+
+The examples below use the `deploy-tools` console script; `python -m deploy_tools` is
+equivalent if you prefer to invoke the module directly.
+
+```
+deployment_root = /path/to/deployment/root
+config_folder = /path/to/config/folder
+
+# Validate the deployment configuration files, also ensuring that the required updates
+# are compatible with the previous deployments.
+deploy-tools validate $deployment_root $config_folder
+
+# Synchronise the deployment area with the configuration files. This will first run
+# validation as part of determining the required changes
+deploy-tools sync $deployment_root $config_folder
+
+# Compare the current deployment snapshot against what is actually deployed in the
+# deployment area. Run this before a deploy to confirm a healthy state.
+deploy-tools compare $deployment_root
+
+```
+
+Generating the JSON schema files with `deploy-tools schema <folder>` is a separate,
+occasional task: it produces the schemas that editors use to validate configuration files,
+and is not part of a deployment. See the schema reference in the documentation.
+
+<!-- README only content. Anything below this line won't be included in index.md -->
+
+See https://diamondlightsource.github.io/deploy-tools for more detailed documentation.

dls_deploy_tools-0.8.0/docs/cli.md

@@ -0,0 +1,9 @@
+# Command-line interface
+
+`deploy-tools` is driven entirely through its command-line interface.
+
+```{typer} deploy_tools.__main__:app
+:prog: deploy-tools
+:make-sections:
+:show-nested:
+```

{dls_deploy_tools-0.7 → dls_deploy_tools-0.8.0}/docs/conf.py

@@ -49,11 +49,20 @@ extensions = [
     "sphinx_design",
     # So we can write markdown files
     "myst_parser",
+    # For the generation of schema docs
+    "sphinx-jsonschema",
+    # Render Pydantic models cleanly (hides internals like model_config / FieldInfo)
+    "sphinxcontrib.autodoc_pydantic",
+    # Render the Typer command-line interface
+    "sphinxcontrib.typer",
 ]
 
 # So we can use the ::: syntax
 myst_enable_extensions = ["colon_fence"]
 
+# Generate anchors for headings (levels 1-3) so pages can link to sections.
+myst_heading_anchors = 3
+
 # If true, Sphinx will warn about all references where the target cannot
 # be found.
 nitpicky = True
@@ -71,11 +80,24 @@ nitpick_ignore = [
     ("py:class", "'object'"),
     ("py:class", "'id'"),
     ("py:class", "typing_extensions.Literal"),
+    # Generic type variable used in save_and_load.load_from_yaml
+    ("py:class", "T"),
+    # PEP 695 type aliases in models.deployment cannot be resolved as classes
+    ("py:class", "deploy_tools.models.deployment.DefaultVersionsByName"),
+    ("py:class", "deploy_tools.models.deployment.ModuleVersionsByName"),
+    ("py:class", "deploy_tools.models.deployment.ReleasesByNameAndVersion"),
+    ("py:class", "deploy_tools.models.deployment.ReleasesByVersion"),
+    ("py:class", "deploy_tools.models.deployment.ModulesByName"),
+    ("py:class", "deploy_tools.models.apptainer_app.MountPoint"),
+    # Pydantic's FieldInfo leaks from the discriminated-union default in the
+    # models.module.Application type alias when rendered in signatures
+    ("py:class", "FieldInfo"),
 ]
 
-# Both the class’ and the __init__ method’s docstring are concatenated and
-# inserted into the main body of the autoclass directive
-autoclass_content = "both"
+# Use only the class docstring in the main body of the autoclass directive. The
+# __init__ docstring is excluded because Pydantic's autogenerated BaseModel.__init__
+# docstring references unresolvable targets (self, ValidationError) under nitpicky mode.
+autoclass_content = "class"
 
 # Order the members by the order they appear in the source code
 autodoc_member_order = "bysource"
@@ -83,8 +105,17 @@ autodoc_member_order = "bysource"
 # Don't inherit docstrings from baseclasses
 autodoc_inherit_docstrings = False
 
-# Document only what is in __all__
-autosummary_ignore_module_all = False
+# Ignore module __all__ so every public member is documented. Internals are kept out
+# of the docs by marking them private with a leading underscore instead.
+autosummary_ignore_module_all = True
+
+# Set global options for sphinx-jsonschema
+jsonschema_options = {
+    "lift_description": True,
+    "lift_definitions": True,
+    "auto_target": True,
+    "auto_reference": True,
+}
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -109,7 +140,10 @@ pygments_style = "sphinx"
 
 # This means you can link things like `str` and `asyncio` to the relevant
 # docs in the python documentation.
-intersphinx_mapping = {"python": ("https://docs.python.org/3/", None)}
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "pydantic": ("https://docs.pydantic.dev/latest/", None),
+}
 
 # A dictionary of graphviz graph attributes for inheritance diagrams.
 inheritance_graph_attrs = {"rankdir": "TB"}

dls_deploy_tools-0.8.0/docs/explanations/default-versions.md

@@ -0,0 +1,48 @@
+# Default version resolution
+
+When a user runs `module load <name>` without a version, Environment Modules must pick
+one. By default it picks the lexically last version, which is often wrong: `1.10` sorts
+before `1.9`, and an unfinished alpha might also win. `deploy-tools` allows you to make
+an explicit choice, and otherwise uses the `natsort` library for a more reasonable default.
+
+## Every Module has a specific default configured
+
+For every live module name, `deploy-tools` writes a `.version` file in its modulefiles
+folder (`modulefiles/<name>/.version`) containing a `set ModulesVersion <version>` line.
+It is written even if the configuration does not have an explicit default, so Environment
+Modules never guesses.
+
+The version it records is resolved as follows:
+
+1. **An explicit default has priority.** If `settings.default_versions` names a version,
+   it is used. It must be a live (non-deprecated) version that exists, or validation fails.
+2. **Otherwise the highest eligible version is chosen automatically**, by natural version
+   sorting (see below), considering only versions *not* marked `exclude_from_defaults`.
+
+Deprecated versions are never candidates and never get a `.version` file.
+
+## Natural version sorting
+
+Automatic selection uses [`natsort`](https://natsort.readthedocs.io) rather than plain
+string comparison, so `1.10` sorts after `1.9`. It also uses natsort's key for
+pre-release schemes, so pre-release tags sort *before* the release they lead up to:
+
+```text
+1.2alpha1  <  1.2rc1  <  1.2  <  1.2.1
+```
+
+So publishing `1.2rc1` does not make it the default while `1.2` exists, and publishing
+`1.2` makes it the default over its own release candidates. Be aware that `1.3alpha1` still
+sorts after `1.2.1`, however; to keep alphas or similar out of the automatic default, mark
+them `exclude_from_defaults: true`.
+
+## Excluding a version from the automatic default
+
+Marking a version `exclude_from_defaults: true` keeps it out of *automatic* selection
+while still allowing it to be set explicitly. Use this to publish an alpha or beta that
+users can opt into with `module load <name>/<version>` without it ever being handed to
+someone who just typed `module load <name>`.
+
+One safety check applies: if *every* version of a name is excluded and no explicit default
+is given, validation fails rather than leave the Module with no default. Either give an
+explicit default or keep at least one non-excluded version.

dls_deploy_tools-0.8.0/docs/explanations/deployment-area.md

@@ -0,0 +1,74 @@
+# The deployment area
+
+The *deployment area* is the directory tree that `deploy-tools` writes into. It is normally
+a shared filesystem location that end users put on their `MODULEPATH`, so its layout is
+important to the end user. This page explains what lives where, and why.
+
+## Layout
+
+Everything below is created and maintained by `deploy-tools`; nothing in the area is meant
+to be edited by hand.
+
+```text
+<deployment root>/
+├── deployment.yaml          # snapshot of the deployed configuration
+├── modules/                 # Modules Area — the built files for every Module
+│   └── <name>/<version>/
+│       ├── modulefile        # the Environment Modules (Tcl) file
+│       ├── entrypoints/      # the executables added to PATH on module load
+│       ├── module.yaml       # this Module's configuration snapshot
+│       └── sif_files/        # Apptainer images, when the Module uses any
+├── modulefiles/             # Modulefiles Area — placed on MODULEPATH
+│   └── <name>/
+│       ├── <version>         # absolute symlink into modules/<name>/<version>/modulefile
+│       └── .version          # records the default version (see below)
+├── deprecated/              # Deprecated Area
+│   └── modulefiles/         # mirrors the Modulefiles Area — optionally on MODULEPATH
+│       └── <name>/<version>  # symlink for a deprecated Module version
+└── build/                   # transient build area (default location)
+```
+
+The split between the **Modules Area** (`modules/`) and the **Modulefiles Area**
+(`modulefiles/`) is the central design choice. The Modules Area holds the real files for
+*every* version that has been deployed and not removed, both live and deprecated. The
+Modulefiles Area holds only a thin tree of symlinks, one per version, pointing at the
+corresponding `modulefile`. Users put only the *modulefiles* directories on their
+`MODULEPATH`, making each Module visible to `module avail` and `module load`.
+
+Deprecation is therefore cheap and reversible: the built files never move, only the symlink
+moves between `modulefiles/` and `deprecated/modulefiles/`. See
+[the release lifecycle](deprecation-lifecycle.md#configuration-is-declarative) for
+the full set of transitions.
+
+## The build area
+
+Modules are first assembled under the **build area** (`build/` by default), then moved into
+the Modules Area. The move is a filesystem `rename`, which is atomic *only when source and
+destination are on the same filesystem* — hence the default build area sits inside the
+deployment root. Building and deploying separately means a half-built Module is never
+visible: either the rename succeeds and the whole version appears, or nothing changes.
+
+The transient `build/` directory and the large Apptainer `sif_files/` images are
+deliberately kept out of the deployment area's git history (see
+[snapshots and the compare safety net](snapshots-and-compare.md)). They are reference-only
+data used by the `compare` command, not something to revert to.
+
+## Why modulefiles embed absolute paths
+
+A generated `modulefile` adds its Module's executables to the user's path with one line:
+
+```tcl
+prepend-path PATH "<deployment root>/modules/<name>/<version>/entrypoints"
+```
+
+That path is **absolute**, so a deployment area cannot be relocated after the fact.
+This is a deliberate trade-off.
+
+A path relative to the modulefile does not work. Environment Modules sources the file
+*through the symlink* under `modulefiles/` without resolving it first (`[info script]`
+/ `ModulesCurrentModulefile` report the link path). A relative path would be interpreted
+relative to the *link's* location — which changes when a Module is deprecated and the link
+moves to a different location in the tree, silently breaking it.
+
+This allows us to use two separate `modulefiles/` folders, corresponding to live and
+deprecated modules, without needing to edit modulefiles after initial creation.

dls_deploy_tools-0.8.0/docs/explanations/deployment-steps.md

@@ -0,0 +1,26 @@
+# The deployment process
+
+A deployment is made up of several conceptual **steps**, deliberately **not** one-to-one
+with the CLI commands: one command may run several steps, and some are never exposed as
+a command of their own. For the commands themselves see the [CLI reference](../cli.md).
+
+| Step | Description | Run by |
+|------|-------------|--------|
+| Compare | Compare the current deployment snapshot against the modulefiles and built modules that actually exist, confirming the [deployment area](deployment-area.md) is healthy. | `compare` |
+| Validate | Diff the new configuration against the current snapshot to determine the set of actions to take, and check those actions are permitted by the [lifecycle guard rails](deprecation-lifecycle.md#the-guard-rails). | `validate`, `sync` |
+| Build | Generate entrypoint scripts, configuration files and environment variables for each changed Module, writing them to the build area. | `sync` (`validate --test-build`) |
+| Deploy | Move the built Modules from the build area into the Modules Area, link each modulefile into the live or deprecated tree according to its status, and update default versions. | `sync` |
+
+## Why build and deploy are not separate commands
+
+There is no standalone `build` or `deploy` command. `sync` always runs them together, so
+a half-built Module is never exposed to users: either a version is built *and* linked into
+place, or nothing changes.
+
+## How the steps fit together
+
+`sync` is the only step that writes to the deployment area; `compare` and `validate` are
+read-only checks run before it. See
+[snapshots and the compare safety net](snapshots-and-compare.md) for how the snapshot
+ties them together, and [drive deploy-tools from CI](../how-to/ci-pipeline.md) for the
+order to run them in.