From 22815f4bb0dcfcded198cf62793b82385b865c6a Mon Sep 17 00:00:00 2001 From: Martin Gaughran Date: Thu, 20 Feb 2025 20:58:35 +0000 Subject: [PATCH 1/6] Add explicit option to include test build in validate CLI command --- .vscode/launch.json | 12 +++++++++++- .vscode/tasks.json | 12 +++++++++++- src/deploy_tools/__main__.py | 8 ++++++-- src/deploy_tools/validate.py | 11 +++++++---- 4 files changed, 35 insertions(+), 8 deletions(-) diff --git a/.vscode/launch.json b/.vscode/launch.json index ba08027..68105fa 100644 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -38,7 +38,7 @@ "request": "launch", "justMyCode": false, "program": "/venv/bin/deploy-tools", - "args": "validate ${input:from-scratch} ${input:deploy-folder} ${input:config-folder}", + "args": "validate ${input:from-scratch} ${input:test-build} ${input:deploy-folder} ${input:config-folder}", "console": "integratedTerminal", "env": { // Enable break on exception when debugging tests (see: tests/conftest.py) @@ -111,5 +111,15 @@ "default": "--no-use-previous", "type": "pickString" }, + { + "id": "test-build", + "description": "Include test build of the deployment changes", + "options": [ + "--test-build", + "--no-test-build" + ], + "default": "--test-build", + "type": "pickString" + }, ] } diff --git a/.vscode/tasks.json b/.vscode/tasks.json index dabc158..4f7fcb7 100644 --- a/.vscode/tasks.json +++ b/.vscode/tasks.json @@ -33,7 +33,7 @@ { "label": "Validate deployment", "type": "shell", - "command": "deploy-tools validate ${input:from-scratch} ${input:deploy-folder} ${input:config-folder}", + "command": "deploy-tools validate ${input:from-scratch} ${input:test-build} ${input:deploy-folder} ${input:config-folder}", "problemMatcher": [] }, { @@ -82,5 +82,15 @@ "default": "--no-use-previous", "type": "pickString" }, + { + "id": "test-build", + "description": "Include test build of the deployment changes", + "options": [ + "--test-build", + "--no-test-build" + ], + "default": "--test-build", + "type": "pickString" + }, ] } diff --git a/src/deploy_tools/__main__.py b/src/deploy_tools/__main__.py index e08516d..7646587 100644 --- a/src/deploy_tools/__main__.py +++ b/src/deploy_tools/__main__.py @@ -64,12 +64,16 @@ def validate( ), ], from_scratch: Annotated[bool, typer.Option()] = False, + test_build: Annotated[bool, typer.Option()] = True, ) -> None: """Validate deployment configuration and print a list of expected module changes. - This is the same validation that the deploy-tools sync command uses. + If specified, this includes a test build of the provided configuration. The + configuration validation is the same as used by the deploy-tools sync command. """ - validate_and_check_configuration(deployment_root, config_folder, from_scratch) + validate_and_check_configuration( + deployment_root, config_folder, from_scratch, test_build + ) @app.command(no_args_is_help=True) diff --git a/src/deploy_tools/validate.py b/src/deploy_tools/validate.py index e0a33ad..c52d0ea 100644 --- a/src/deploy_tools/validate.py +++ b/src/deploy_tools/validate.py @@ -26,7 +26,10 @@ class ValidationError(Exception): def validate_and_check_configuration( - deployment_root: Path, config_folder: Path, from_scratch: bool = False + deployment_root: Path, + config_folder: Path, + from_scratch: bool = False, + test_build: bool = True, ) -> None: """Validate deployment config and check that deploy can run in deployment area.""" with TemporaryDirectory() as build_dir: @@ -37,12 +40,12 @@ def validate_and_check_configuration( deployment_changes = validate_deployment_changes( deployment, snapshot, from_scratch ) + snapshot_default_versions = validate_default_versions(snapshot) check_deploy_can_run(deployment_changes, layout) + if test_build: + build(deployment_changes, layout) - build(deployment_changes, layout) - - snapshot_default_versions = validate_default_versions(snapshot) print_updates(snapshot_default_versions, deployment_changes) From 4ff3121d7772ee325e3f2e55bb52348677b38d41 Mon Sep 17 00:00:00 2001 From: Martin Gaughran Date: Thu, 20 Feb 2025 21:27:49 +0000 Subject: [PATCH 2/6] Add help messages for CLI arguments and options --- src/deploy_tools/__main__.py | 110 ++++++++++++++++------------------- 1 file changed, 51 insertions(+), 59 deletions(-) diff --git a/src/deploy_tools/__main__.py b/src/deploy_tools/__main__.py index 7646587..6c63936 100644 --- a/src/deploy_tools/__main__.py +++ b/src/deploy_tools/__main__.py @@ -12,29 +12,54 @@ __all__ = ["main"] +DEPLOYMENT_ROOT_ARGUMENT = Annotated[ + Path, + typer.Argument( + exists=True, + file_okay=False, + dir_okay=True, + writable=True, + help="Root of the deployment area to use.", + ), +] +CONFIG_FOLDER_ARGUMENT = Annotated[ + Path, + typer.Argument( + exists=True, + file_okay=False, + dir_okay=True, + help="Folder containing configuration for deployment.", + ), +] +SCHEMA_OUTPUT_PATH_ARGUMENT = Annotated[ + Path, + typer.Argument( + exists=True, + file_okay=False, + dir_okay=True, + writable=True, + help="Output path to write all .json schema files to.", + ), +] +FROM_SCRATCH_OPTION = Annotated[ + bool, typer.Option(help="Deploy into an empty deployment area.") +] +TEST_BUILD_OPTION = Annotated[ + bool, typer.Option(help="Test the build process in a temporary directory.") +] +USE_PREVIOUS_OPTION = Annotated[ + bool, typer.Option(help="Use previous deployment snapshot for comparison.") +] + + app = typer.Typer(no_args_is_help=True) @app.command(no_args_is_help=True) def sync( - deployment_root: Annotated[ - Path, - typer.Argument( - exists=True, - file_okay=False, - dir_okay=True, - writable=True, - ), - ], - config_folder: Annotated[ - Path, - typer.Argument( - exists=True, - file_okay=False, - dir_okay=True, - ), - ], - from_scratch: Annotated[bool, typer.Option()] = False, + deployment_root: DEPLOYMENT_ROOT_ARGUMENT, + config_folder: CONFIG_FOLDER_ARGUMENT, + from_scratch: FROM_SCRATCH_OPTION = False, ) -> None: """Synchronise deployment root with current configuration. @@ -46,25 +71,10 @@ def sync( @app.command(no_args_is_help=True) def validate( - deployment_root: Annotated[ - Path, - typer.Argument( - exists=True, - file_okay=False, - dir_okay=True, - writable=True, - ), - ], - config_folder: Annotated[ - Path, - typer.Argument( - exists=True, - file_okay=False, - dir_okay=True, - ), - ], - from_scratch: Annotated[bool, typer.Option()] = False, - test_build: Annotated[bool, typer.Option()] = True, + deployment_root: DEPLOYMENT_ROOT_ARGUMENT, + config_folder: CONFIG_FOLDER_ARGUMENT, + from_scratch: FROM_SCRATCH_OPTION = False, + test_build: TEST_BUILD_OPTION = True, ) -> None: """Validate deployment configuration and print a list of expected module changes. @@ -78,16 +88,8 @@ def validate( @app.command(no_args_is_help=True) def compare( - deployment_root: Annotated[ - Path, - typer.Argument( - exists=True, - file_okay=False, - dir_okay=True, - writable=True, - ), - ], - use_previous: Annotated[bool, typer.Option()] = False, + deployment_root: DEPLOYMENT_ROOT_ARGUMENT, + use_previous: USE_PREVIOUS_OPTION = False, ) -> None: """Compare the deployment snapshot to deployed modules in the deployment root. @@ -99,17 +101,7 @@ def compare( @app.command(no_args_is_help=True) -def schema( - output_path: Annotated[ - Path, - typer.Argument( - exists=True, - file_okay=False, - dir_okay=True, - writable=True, - ), - ], -) -> None: +def schema(output_path: SCHEMA_OUTPUT_PATH_ARGUMENT) -> None: """Generate JSON schemas for yaml configuration files.""" generate_schema(output_path) @@ -126,7 +118,7 @@ def common( version: bool = typer.Option( None, "--version", - help="Show program's version number and exit", + help="Show program's version number and exit.", callback=version_callback, ), ) -> None: From cdf80afea249c82421934fe01fefdd77bcabe769 Mon Sep 17 00:00:00 2001 From: Martin Gaughran Date: Thu, 20 Feb 2025 22:47:03 +0000 Subject: [PATCH 3/6] Use yaml diff as output for Compare command --- src/deploy_tools/compare.py | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/src/deploy_tools/compare.py b/src/deploy_tools/compare.py index f65bdba..816fb63 100644 --- a/src/deploy_tools/compare.py +++ b/src/deploy_tools/compare.py @@ -1,5 +1,10 @@ +import difflib from collections import defaultdict from pathlib import Path +from typing import Any + +import yaml +from pydantic import TypeAdapter from .layout import Layout from .models.deployment import ( @@ -97,7 +102,7 @@ def _get_deprecated_status(name: str, version: str, layout: Layout) -> bool: return True raise ComparisonError( - f"Modulefile for {name}/{version} not found. Comparison with snapshot failed." + f"Modulefile for {name}/{version} not found in deployment area." ) @@ -122,8 +127,8 @@ def _compare_snapshot_to_actual(snapshot: Deployment, actual: Deployment) -> Non def _compare_releases(snapshot: Deployment, actual: Deployment) -> None: if snapshot.releases != actual.releases: raise ComparisonError( - f"Snapshot and actual release configuration do not match, see:\n" - f"Snapshot: {snapshot.releases}\nActual: {actual.releases}" + "Snapshot and actual release configuration do not match, see:\n" + + _get_dict_diff(snapshot.releases, actual.releases) ) @@ -133,6 +138,20 @@ def _compare_default_versions(snapshot: Deployment, actual: Deployment) -> None: if snapshot_defaults != actual_defaults: raise ComparisonError( - f"Snapshot and actual module default versions do not match, see:\n" - f"Snapshot: {snapshot_defaults}\nActual: {actual_defaults}" + "Snapshot and actual module default versions do not match, see:\n" + + _get_dict_diff(snapshot_defaults, actual_defaults) + ) + + +def _get_dict_diff(d1: dict[str, Any], d2: dict[str, Any]): + return "\n" + "\n".join( + difflib.ndiff( + _yaml_dumps(d1).splitlines(), + _yaml_dumps(d2).splitlines(), ) + ) + + +def _yaml_dumps(obj: dict[str, Any], indent: int | None = None) -> str: + ta = TypeAdapter(dict[str, Any]) + return yaml.safe_dump(ta.dump_python(obj), indent=indent) From f4bfd20923915b3343206d910ac69a0c612735d2 Mon Sep 17 00:00:00 2001 From: Martin Gaughran Date: Thu, 20 Feb 2025 23:36:10 +0000 Subject: [PATCH 4/6] Clear up README and add explanations of the primary build steps --- README.md | 90 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 58 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 0308f76..3a8486a 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,9 @@ 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. +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 | :---: | :---: @@ -16,9 +18,9 @@ PyPI | `pip install dls-deploy-tools` Docker | `docker run ghcr.io/diamondlightsource/deploy-tools:latest` Releases | -The demo_configuration folder can be passed as the config_folder to the deploy-tools -commands. The deployment_root just needs to be a writeable location for all files to get -deployed under. +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. ``` deployment_root = /path/to/deployment/root @@ -38,37 +40,61 @@ python -m deploy_tools sync $deployment_root $config_folder ``` -## VSCode Tasks and Debug Configuration +## Deployment Steps -The following tasks are configured for VSCode, to allow for local testing of deploy-tools. These tasks (plus their default input) should create a separate `demo-output` folder at the top-level of the project folder. In addition, separate Debug configurations are also provided, corresponding to these same commands. +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. -The equivalent CLI commands are included for reference, but it is recommended that you use `--help` to explore the commands, arguments and options in greater detail. +|**Step**|**Description** | +|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +|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 | +|Check |With the set of expected changes, perform some basic checks of the deployment area to ensure there are no major issues preventing the Deploy step from running | +|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| -| **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 check that all expected Deploy operations are unlikely to fail | -| Compare deployment to snapshot | `deploy-tools compare` | Compare the configuration stored from the last Sync run, with the state of any deployed Modules. This may be useful in the event of a failed Sync process | + +## 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 `|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 check that all expected Deploy operations are unlikely to fail. This will also 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 -|**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. | -|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. As of writing, there are 2 types of Application: `Apptainer` and `Shell` (Bash script) | -|Deployment Area |The filesystem location where all Modules are to be deployed. This is typically a shared filesystem location for general use by multiple people | -|Deployment Root |Refers to the filesystem path at the root of the Deployment Area. The term 'Root' is used similarly for other directories | -|Build (verb) |Generate entrypoint scripts, configuration files and environment variables for a given Module. These are output to the Build Area | -|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 | -|Deploy |Act of moving built Modules from the Build Area into the Modules Area. A copy of the modulefile is moved to either the Modulefiles Folder or Deprecated Folder, depending on its deprecation status. The Module can then be used by the End User | -|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. Where possible, the use of deprecated modules by the End User should be avoided| -|Release (noun) |A Module, including version, alongside its lifecycle (i.e. deprecation) status | -|Deployment |The sum total of all releases (deprecated or not) that are to be maintained in the deployment area | -|End User |Refers to anybody who is intended to make use of a deployed Module. This can include the people modifying configuration themselves | +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. | +|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. 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 | +|Deployment Root |Refers to the filesystem path at the root of the Deployment Area. The term 'Root' is used similarly for other directories | +|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. | +|Release (noun) |A Module, including version, alongside its lifecycle (i.e. deprecation) status | +|Deployment |The sum total of all releases (deprecated or not) that are to be maintained in the deployment area | +|End User |Refers to anybody who is intending to make use of a deployed Module. This can include the people modifying configuration themselves | From 491de2096351bcf86775540d47372849db49e58a Mon Sep 17 00:00:00 2001 From: Martin Gaughran Date: Mon, 24 Feb 2025 10:53:42 +0000 Subject: [PATCH 5/6] Improve README --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 3a8486a..383af0c 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ python -m deploy_tools schema $schema_folder python -m deploy_tools validate $deployment_root $config_folder # Synchronise the deployment area with the configuration files. This will first run -# validation +# validation as part of determining the required changes python -m deploy_tools sync $deployment_root $config_folder ``` @@ -85,16 +85,16 @@ See the Deployment Steps above for an overview of the primary stages of a deploy |-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |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 | -|Deployment Root |Refers to the filesystem path at the root of the Deployment Area. The term 'Root' is used similarly for other directories | +|(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. | -|Release (noun) |A Module, including version, alongside its lifecycle (i.e. deprecation) status | -|Deployment |The sum total of all releases (deprecated or not) that are to be maintained in the deployment area | |End User |Refers to anybody who is intending to make use of a deployed Module. This can include the people modifying configuration themselves | From e1edeba22cd447f82e72255d39b842dd125a8a46 Mon Sep 17 00:00:00 2001 From: Martin Gaughran Date: Mon, 24 Feb 2025 10:58:25 +0000 Subject: [PATCH 6/6] Add explanation of JSON schemas to README --- README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/README.md b/README.md index 383af0c..ff3604f 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,17 @@ bit different to the CLI commands; see `deploy-tools --help` for more informatio |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. + +We strongly recommend that you provide a schema for configuration file validation. The relevant lines at the top of each release file are: + +```# 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