Write a Module configuration#

To add or change a Module, you edit YAML in the configuration folder. This guide covers the mechanics. For the shape of the files and every field they take, see the configuration reference; to point your editor at the matching schema, the schema reference.

Add a new Module version#

Create the Release file at <config folder>/<name>/<version>.yaml. The folder name is the Module name and the filename is the version, so phoebus/0.1.yaml defines version 0.1 of phoebus. The name and version inside the file must match the path.
Add the schema line as the first line so your editor validates as you type:
```
# yaml-language-server: $schema=https://raw.githubusercontent.com/DiamondLightSource/deploy-tools/main/src/deploy_tools/models/schemas/release.json
```
The line is read by yaml-language-server, so it takes effect in VS Code with the Red Hat YAML extension or any other editor running that language server; elsewhere it is an inert comment. See the schema reference for details.
Define the Module. Most Modules provide one or more applications; the smallest useful one is a single shell script:
```
module:
  name: my-module
  version: "1.0"
  description: What this Module provides
  applications:
    - app_type: shell
      name: hello
      script:
        - echo "hello from my-module"
```
Swap the application for an apptainer or binary one as needed — see the three application types.

A Module doesn’t have to provide an application: it can instead just set environment variables or pull in other Modules as dependencies. Give such a Module an empty applications: [].

Set the default version#

module load <name> with no version loads the default. If you don’t choose one the highest version is picked automatically; to pin a specific version, add it to settings.yaml:

default_versions:
  my-module: "1.0"

settings.yaml can take a schema line of its own, as above, pointing at deployment-settings.json.

To keep a version out of automatic selection — an alpha or release candidate, say — while still allowing an explicit module load <name>/<version>, set exclude_from_defaults: true on that Module.

See default version resolution for how the automatic choice is made.

Get your change deployed#

How your change reaches the deployment area depends on how your site runs deploy-tools. The recommended setup is a CI pipeline in the configuration repository: you open a merge request, CI validates the change, and merging it deploys (see drive deploy-tools from CI). CI is not a requirement — an administrator can run the same validate and sync commands by hand instead. Either way, the yaml-language-server schema line catches structural mistakes in your editor as you type, before anyone else looks at the change.

Change or retire a version#

Update an existing version in place. Rejected by default so published versions stay stable; prefer publishing a new version. If you must, set allow_updates: true on the Module — see the guard rails.
Retire a version. Set deprecated: true in the Release file to steer users away from it. Deleting it outright has to wait until after it is deprecated (unless the Module has allow_updates: true). See the guard rails.