From a33521154e778698d5bd97da4bf786aabdc4e86f Mon Sep 17 00:00:00 2001 From: Martin Gaughran Date: Thu, 30 Jul 2026 11:52:14 +0000 Subject: [PATCH 01/10] Remove docs "Work in progress" notice in README --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6682af9..7b53600 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ What | Where Source | PyPI | `pip install dls-deploy-tools` Docker | `docker run ghcr.io/diamondlightsource/deploy-tools:latest` -Documentation | Work in progress +Documentation | Releases | The demo_configuration folder in this repository can be passed as the config_folder to From 31cbf5af727b60c31a18bd756b31f2401aee93dc Mon Sep 17 00:00:00 2001 From: Martin Gaughran Date: Fri, 31 Jul 2026 15:27:36 +0000 Subject: [PATCH 02/10] Remove redundant schema information from README --- README.md | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/README.md b/README.md index 7b53600..77f43ad 100644 --- a/README.md +++ b/README.md @@ -65,21 +65,6 @@ each step. See `deploy-tools --help` for more detail. There is no standalone `build` or `deploy` command: `sync` always runs them together, so a half-built Module is never exposed to users. -## JSON Schema - -A set of JSON schema files are provided under `src/deploy_tools/models/schemas`. These are generated from the Pydantic models in `src/deploy_tools/models/` by the `deploy-tools schema` command (see `models/schema.py`). - -We strongly recommend that you provide a schema for configuration file validation, by adding a `yaml-language-server` comment to the top of each configuration file. For production configuration, point this at the schema files hosted on GitHub: - -```# yaml-language-server: $schema=https://raw.githubusercontent.com/DiamondLightSource/deploy-tools/main/src/deploy_tools/models/schemas/release.json``` - -Use `release.json` for the per-version Module files (`/.yaml`) and -`deployment-settings.json` for the top-level `settings.yaml`. - -As the demo_configuration is used during development, we instead set it to use the locally generated schemas via an absolute workspace path (e.g. `/workspaces/deploy-tools/src/deploy_tools/models/schemas/release.json`). This dev-container-only path should not be used for production configuration. - -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. - ## CLI Commands, VSCode Tasks and Debug Configuration The following CLI commands are used in our CI/CD process to update the Deployment Area From 070a50cd1c59be6f92c5d319d32b660c3305b2a0 Mon Sep 17 00:00:00 2001 From: Martin Gaughran Date: Fri, 31 Jul 2026 15:27:36 +0000 Subject: [PATCH 03/10] Remove redundant CLI command and VSCode task information from README --- README.md | 30 ------------------------------ 1 file changed, 30 deletions(-) diff --git a/README.md b/README.md index 77f43ad..7123c5e 100644 --- a/README.md +++ b/README.md @@ -65,36 +65,6 @@ each step. See `deploy-tools --help` for more detail. There is no standalone `build` or `deploy` command: `sync` always runs them together, so a half-built Module is never exposed to users. -## 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 when starting from a clean Deployment -Area, as there is no snapshot from a prior Deploy step: - -- `sync`/`validate --from-scratch` work against an empty area without expecting a - snapshot, and imply `--allow-all` (there is no prior state to enforce lifecycle rules - against). -- `compare --from-scratch` just checks the Deployment Area exists and is **empty**. Run - this in CI before the first deploy, where a normal `compare` has no snapshot to use. - -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 `|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. From d2180a135d387537fd458509a11c75692c3ccaf0 Mon Sep 17 00:00:00 2001 From: Martin Gaughran Date: Mon, 27 Jul 2026 18:22:55 +0000 Subject: [PATCH 04/10] Move deployment steps from README into separate page --- README.md | 16 ---------------- docs/explanations.md | 1 + docs/explanations/deployment-steps.md | 26 ++++++++++++++++++++++++++ 3 files changed, 27 insertions(+), 16 deletions(-) create mode 100644 docs/explanations/deployment-steps.md diff --git a/README.md b/README.md index 7123c5e..26eecb3 100644 --- a/README.md +++ b/README.md @@ -49,22 +49,6 @@ deploy-tools compare $deployment_root ``` -## Deployment Steps - -There are several key conceptual steps that make up the deployment process. These are -**not** one-to-one with the CLI commands; the "Run by" column shows which command runs -each step. See `deploy-tools --help` for more detail. - -|**Step**|**Description** |**Run by**| -|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------| -|Compare |Compare the current deployment snapshot file with the modulefiles and built modules that currently exist. This ensures that the Deployment Area is in a healthy state |`compare` | -|Validate|Process the updated configuration. By comparing the new configuration files with the current deployment snapshot from the last sync, we determine the set of actions that need to be taken |`validate`, `sync`| -|Build |Generate entrypoint scripts, configuration files and environment variables for a given Module. These are output to the Build Area |`sync` (`validate --test-build`)| -|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|`sync` | - -There is no standalone `build` or `deploy` command: `sync` always runs them together, so -a half-built Module is never exposed to users. - ## Glossary See the Deployment Steps above for an overview of the primary stages of a deployment. diff --git a/docs/explanations.md b/docs/explanations.md index 3a758d1..c2b70f1 100644 --- a/docs/explanations.md +++ b/docs/explanations.md @@ -5,6 +5,7 @@ Explanations of how it works and why it works that way. ```{toctree} :maxdepth: 1 +explanations/deployment-steps explanations/deployment-area explanations/snapshots-and-compare explanations/deprecation-lifecycle diff --git a/docs/explanations/deployment-steps.md b/docs/explanations/deployment-steps.md new file mode 100644 index 0000000..349a5a4 --- /dev/null +++ b/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 [release lifecycle](deprecation-lifecycle.md). | `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 a pipeline runs them in. From 7ef5639f47bfa2cb8820646ee82903151cf87a2d Mon Sep 17 00:00:00 2001 From: Martin Gaughran Date: Mon, 27 Jul 2026 19:03:05 +0000 Subject: [PATCH 05/10] Split off Glossary into separate docs page --- README.md | 22 ---------------------- docs/glossary.md | 23 +++++++++++++++++++++++ docs/reference.md | 1 + 3 files changed, 24 insertions(+), 22 deletions(-) create mode 100644 docs/glossary.md diff --git a/README.md b/README.md index 26eecb3..c7909ae 100644 --- a/README.md +++ b/README.md @@ -49,28 +49,6 @@ deploy-tools compare $deployment_root ``` -## 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. There are 3 types of Application: `Apptainer` (an executable container image), `Shell` (a Bash script) and `Binary` (an executable downloaded from a URL and verified against a hash) | -|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 | - See https://diamondlightsource.github.io/deploy-tools for more detailed documentation. diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 0000000..963aa1b --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,23 @@ +# Glossary + +See [the deployment process](explanations/deployment-steps.md) for an overview of the +primary stages of a deployment, and [the deployment area](explanations/deployment-area.md) +for the on-disk layout these terms refer to. + +| Term | Definition | +|------|------------| +| Environment Modules | A [standard package for Linux](https://modules.readthedocs.io/en/latest/) that provides the commands for loading and unloading 'Environment Modules' (each defined by a Modulefile). 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](explanations/deprecation-lifecycle.md) (i.e. deprecation) status. | +| Application | Each Module can be configured with multiple Applications, each one providing one or more executables. There are 3 types of Application: `Apptainer` (an executable container image), `Shell` (a Bash script) and `Binary` (an executable downloaded from a URL and verified against a hash). | +| 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; e.g. the Deployment Root is the root of the Deployment Area. | +| Deployment Step | Refers to one of the primary steps that make up the Deployment process. See [the deployment process](explanations/deployment-steps.md) 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 live (non-deprecated) Modules can then be accessed by the End User using the standard Environment Modules interface (`module avail`, etc.). Deprecated Modules live in the separate Deprecated Folder. | +| Deprecate | Moving a modulefile to the separate Deprecated Folder, to indicate that its use should be discouraged. See [the release lifecycle](explanations/deprecation-lifecycle.md). | +| 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. | diff --git a/docs/reference.md b/docs/reference.md index 25d6f77..da6115c 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -9,6 +9,7 @@ Technical reference material including APIs and release notes. CLI API <_api/deploy_tools> Schemas +Glossary genindex Release Notes ``` From 357c76fe154aa75517432012412322f5030e6ae3 Mon Sep 17 00:00:00 2001 From: Martin Gaughran Date: Thu, 30 Jul 2026 11:53:10 +0000 Subject: [PATCH 06/10] Improve schema command description in README --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index c7909ae..8263b9a 100644 --- a/README.md +++ b/README.md @@ -30,10 +30,6 @@ 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 -deploy-tools schema $schema_folder # Validate the deployment configuration files, also ensuring that the required updates # are compatible with the previous deployments. @@ -49,6 +45,10 @@ deploy-tools compare $deployment_root ``` +Generating the JSON schema files with `deploy-tools schema ` 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. + See https://diamondlightsource.github.io/deploy-tools for more detailed documentation. From 2ca0d089910aabbd40739c2135c8c8fcfbd48267 Mon Sep 17 00:00:00 2001 From: Martin Gaughran Date: Thu, 30 Jul 2026 11:53:58 +0000 Subject: [PATCH 07/10] Add note in README to indicate commands are typically run in CI --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index 8263b9a..472a7bb 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,12 @@ 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. +In normal use these commands are not run by hand: they act on a shared deployment area and +belong in a CI pipeline, gated by change review. Running them manually against the demo +configuration, as below, is just 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. From c2da0dddee0f68ff42d3a9a295d8a2a6785f44c4 Mon Sep 17 00:00:00 2001 From: Martin Gaughran Date: Tue, 4 Aug 2026 09:47:32 +0000 Subject: [PATCH 08/10] Use "Area" consistently in documentation --- docs/explanations/deployment-area.md | 10 +++++----- docs/glossary.md | 7 ++++--- 2 files changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/explanations/deployment-area.md b/docs/explanations/deployment-area.md index 064a42c..0f11755 100644 --- a/docs/explanations/deployment-area.md +++ b/docs/explanations/deployment-area.md @@ -18,20 +18,20 @@ to be edited by hand. │ ├── 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 Folder — placed on MODULEPATH +├── modulefiles/ # Modulefiles Area — placed on MODULEPATH │ └── / │ ├── # absolute symlink into modules///modulefile │ └── .version # records the default version (see below) -├── deprecated/ -│ └── modulefiles/ # Deprecated Folder — optionally on MODULEPATH +├── deprecated/ # Deprecated Area +│ └── modulefiles/ # mirrors the Modulefiles Area — optionally on MODULEPATH │ └── / # symlink for a deprecated Module version └── build/ # transient build area (default location) ``` -The split between the **Modules Area** (`modules/`) and the **Modulefiles Folder** +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 Folder holds only a thin tree of symlinks, one per version, pointing at 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`. diff --git a/docs/glossary.md b/docs/glossary.md index 963aa1b..5fd4341 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -13,11 +13,12 @@ for the on-disk layout these terms refer to. | Release (noun) | A Module, including version, alongside its [lifecycle](explanations/deprecation-lifecycle.md) (i.e. deprecation) status. | | Application | Each Module can be configured with multiple Applications, each one providing one or more executables. There are 3 types of Application: `Apptainer` (an executable container image), `Shell` (a Bash script) and `Binary` (an executable downloaded from a URL and verified against a hash). | | 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 | One of the filesystem locations that `deploy-tools` manages for a distinct purpose: the Deployment, Build, Modules, Modulefiles and Deprecated Areas. Lowercase "folder" is used in its plain sense for any other directory, such as the config folder or a Module's entrypoints folder. | | (Area) Root | Refers to the filesystem path at the root of the given Area; e.g. the Deployment Root is the root of the Deployment Area. | | Deployment Step | Refers to one of the primary steps that make up the Deployment process. See [the deployment process](explanations/deployment-steps.md) 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 live (non-deprecated) Modules can then be accessed by the End User using the standard Environment Modules interface (`module avail`, etc.). Deprecated Modules live in the separate Deprecated Folder. | -| Deprecate | Moving a modulefile to the separate Deprecated Folder, to indicate that its use should be discouraged. See [the release lifecycle](explanations/deprecation-lifecycle.md). | -| 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. | +| Modulefiles Area | Refers to the `modulefiles` folder under the Deployment Root. When this path is added to the MODULEPATH environment variable, all live (non-deprecated) Modules can then be accessed by the End User using the standard Environment Modules interface (`module avail`, etc.). Deprecated Modules live in the separate Deprecated Area. | +| Deprecate | Moving a modulefile into the Deprecated Area, to indicate that its use should be discouraged. See [the release lifecycle](explanations/deprecation-lifecycle.md). | +| Deprecated Area | Refers to the `deprecated` folder under the Deployment Root, which holds its own `modulefiles` folder mirroring the Modulefiles Area. By adding that `deprecated/modulefiles` path 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. | From e80d821bf31a650cd58075260d517f8cc1012efc Mon Sep 17 00:00:00 2001 From: Martin Gaughran Date: Tue, 4 Aug 2026 10:49:54 +0000 Subject: [PATCH 09/10] Reorder glossary --- docs/glossary.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/glossary.md b/docs/glossary.md index 5fd4341..22af75b 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -8,17 +8,17 @@ for the on-disk layout these terms refer to. |------|------------| | Environment Modules | A [standard package for Linux](https://modules.readthedocs.io/en/latest/) that provides the commands for loading and unloading 'Environment Modules' (each defined by a Modulefile). 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](explanations/deprecation-lifecycle.md) (i.e. deprecation) status. | | Application | Each Module can be configured with multiple Applications, each one providing one or more executables. There are 3 types of Application: `Apptainer` (an executable container image), `Shell` (a Bash script) and `Binary` (an executable downloaded from a URL and verified against a hash). | -| 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. | +| Release (noun) | A Module, including version, alongside its [lifecycle](explanations/deprecation-lifecycle.md) (i.e. deprecation) status. | +| Deployment | The sum total of all Releases (deprecated or not) that are to be maintained in the Deployment Area. | +| Deployment Step | Refers to one of the primary steps that make up the Deployment process. See [the deployment process](explanations/deployment-steps.md) for a breakdown. | +| End User | Refers to anybody who is intending to make use of a deployed Module. This can include the people modifying configuration themselves. | | Area | One of the filesystem locations that `deploy-tools` manages for a distinct purpose: the Deployment, Build, Modules, Modulefiles and Deprecated Areas. Lowercase "folder" is used in its plain sense for any other directory, such as the config folder or a Module's entrypoints folder. | | (Area) Root | Refers to the filesystem path at the root of the given Area; e.g. the Deployment Root is the root of the Deployment Area. | -| Deployment Step | Refers to one of the primary steps that make up the Deployment process. See [the deployment process](explanations/deployment-steps.md) for a breakdown. | +| 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. | | 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 Area | Refers to the `modulefiles` folder under the Deployment Root. When this path is added to the MODULEPATH environment variable, all live (non-deprecated) Modules can then be accessed by the End User using the standard Environment Modules interface (`module avail`, etc.). Deprecated Modules live in the separate Deprecated Area. | | Deprecate | Moving a modulefile into the Deprecated Area, to indicate that its use should be discouraged. See [the release lifecycle](explanations/deprecation-lifecycle.md). | | Deprecated Area | Refers to the `deprecated` folder under the Deployment Root, which holds its own `modulefiles` folder mirroring the Modulefiles Area. By adding that `deprecated/modulefiles` path 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. | From 2921533cf41826706c765e9e94da3efef78a2a0e Mon Sep 17 00:00:00 2001 From: Martin Gaughran Date: Tue, 4 Aug 2026 09:58:40 +0000 Subject: [PATCH 10/10] Clarify Deployment vs deployment in glossary --- docs/glossary.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/glossary.md b/docs/glossary.md index 22af75b..e53d2cf 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -11,8 +11,8 @@ for the on-disk layout these terms refer to. | 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. | | Application | Each Module can be configured with multiple Applications, each one providing one or more executables. There are 3 types of Application: `Apptainer` (an executable container image), `Shell` (a Bash script) and `Binary` (an executable downloaded from a URL and verified against a hash). | | Release (noun) | A Module, including version, alongside its [lifecycle](explanations/deprecation-lifecycle.md) (i.e. deprecation) status. | -| Deployment | The sum total of all Releases (deprecated or not) that are to be maintained in the Deployment Area. | -| Deployment Step | Refers to one of the primary steps that make up the Deployment process. See [the deployment process](explanations/deployment-steps.md) for a breakdown. | +| Deployment | The declared configuration for a Deployment Area: all Releases (deprecated or not) to be maintained there, plus global settings. Written to the `deployment.yaml` snapshot by `sync`. The act of deploying is written lowercase. | +| Deployment Step | Refers to one of the primary steps that make up the deployment process. See [the deployment process](explanations/deployment-steps.md) for a breakdown. | | End User | Refers to anybody who is intending to make use of a deployed Module. This can include the people modifying configuration themselves. | | Area | One of the filesystem locations that `deploy-tools` manages for a distinct purpose: the Deployment, Build, Modules, Modulefiles and Deprecated Areas. Lowercase "folder" is used in its plain sense for any other directory, such as the config folder or a Module's entrypoints folder. | | (Area) Root | Refers to the filesystem path at the root of the given Area; e.g. the Deployment Root is the root of the Deployment Area. |