From 4ebebc5f120f55f118df0893452245c79f5422c9 Mon Sep 17 00:00:00 2001 From: Martin Gaughran Date: Mon, 27 Jul 2026 19:08:35 +0000 Subject: [PATCH 1/3] Clarify use of schemas in docs --- docs/schemas.md | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/docs/schemas.md b/docs/schemas.md index f1521fb..716960b 100644 --- a/docs/schemas.md +++ b/docs/schemas.md @@ -28,6 +28,14 @@ This requires an editor with a YAML language server — e.g. VS Code with the or any [LSP](https://microsoft.github.io/language-server-protocol/)-capable editor running [`yaml-language-server`](https://github.com/redhat-developer/yaml-language-server). +```{note} +The bundled `demo_configuration` instead points at the locally generated schemas via an +absolute workspace path (e.g. +`/workspaces/deploy-tools/src/deploy_tools/models/schemas/release.json`), so it validates +against uncommitted schema changes during development. This dev-container-only path is not +suitable for production configuration. +``` + The other two generated schemas cover files you don't normally author by hand: `deployment.json` (the `deployment.yaml` snapshot written by `sync`) and `module.json` (the `Module` that a `Release` wraps). @@ -44,8 +52,14 @@ schemas/release ## How the schemas are generated `deploy_tools.models.schema.generate_schema` writes these files from the corresponding -Pydantic models. To regenerate them manually: +Pydantic models. The checked-in schemas under `src/deploy_tools/models/schemas` do not +update automatically when the models change, so after any model change you must regenerate +and commit them. + +The simplest way is the **Generate Schema** VSCode task (see +[the VSCode tasks guide](how-to/vscode-tasks.md)), which writes to the correct location. +Equivalently, run the CLI, pointing it at that folder: ```bash -deploy-tools schema path/to/output/folder +deploy-tools schema src/deploy_tools/models/schemas ``` From 5138a4f8c82d1f798aafd71b5ae16a92a0210b72 Mon Sep 17 00:00:00 2001 From: Martin Gaughran Date: Thu, 30 Jul 2026 18:43:32 +0000 Subject: [PATCH 2/3] Move schema regeneration docs into separate page --- docs/how-to.md | 1 + docs/how-to/regenerate-schemas.md | 16 ++++++++++++++++ docs/schemas.md | 17 ++++------------- 3 files changed, 21 insertions(+), 13 deletions(-) create mode 100644 docs/how-to/regenerate-schemas.md diff --git a/docs/how-to.md b/docs/how-to.md index ac09241..649f7b0 100644 --- a/docs/how-to.md +++ b/docs/how-to.md @@ -8,5 +8,6 @@ Practical step-by-step guides for the more experienced user. how-to/ci-pipeline how-to/run-container how-to/vscode-tasks +how-to/regenerate-schemas how-to/contribute ``` diff --git a/docs/how-to/regenerate-schemas.md b/docs/how-to/regenerate-schemas.md new file mode 100644 index 0000000..37ae7ea --- /dev/null +++ b/docs/how-to/regenerate-schemas.md @@ -0,0 +1,16 @@ +# Regenerate the JSON schemas + +The JSON schema files under `src/deploy_tools/models/schemas` are generated from the +Pydantic models in `src/deploy_tools/models` by +`deploy_tools.models.schema.generate_schema`. They are checked in and do not update +automatically, so after changing any model you must regenerate and commit them. + +The simplest way is the **Generate Schema** VSCode task (see +[the VSCode tasks guide](vscode-tasks.md)), which writes to the correct location. +Equivalently, run the CLI, pointing it at that folder: + +```bash +deploy-tools schema src/deploy_tools/models/schemas +``` + +Commit the regenerated files alongside your model change. diff --git a/docs/schemas.md b/docs/schemas.md index 716960b..05893d6 100644 --- a/docs/schemas.md +++ b/docs/schemas.md @@ -49,17 +49,8 @@ schemas/deployment-settings schemas/release ``` -## How the schemas are generated +## Regenerating the schemas -`deploy_tools.models.schema.generate_schema` writes these files from the corresponding -Pydantic models. The checked-in schemas under `src/deploy_tools/models/schemas` do not -update automatically when the models change, so after any model change you must regenerate -and commit them. - -The simplest way is the **Generate Schema** VSCode task (see -[the VSCode tasks guide](how-to/vscode-tasks.md)), which writes to the correct location. -Equivalently, run the CLI, pointing it at that folder: - -```bash -deploy-tools schema src/deploy_tools/models/schemas -``` +These files are checked in and do not update automatically when the models change. +Contributors who change the models must regenerate them — see +[regenerate the JSON schemas](how-to/regenerate-schemas.md). From 9d6c8b0188d3acf7a4302914d18dac200d0f43f1 Mon Sep 17 00:00:00 2001 From: Martin Gaughran Date: Thu, 30 Jul 2026 19:04:57 +0000 Subject: [PATCH 3/3] Add pre-commit hook to regenerate schema --- .pre-commit-config.yaml | 7 +++++++ docs/how-to/regenerate-schemas.md | 13 ++++++++++--- 2 files changed, 17 insertions(+), 3 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 6c3561d..5408764 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -31,6 +31,13 @@ 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: diff --git a/docs/how-to/regenerate-schemas.md b/docs/how-to/regenerate-schemas.md index 37ae7ea..f707561 100644 --- a/docs/how-to/regenerate-schemas.md +++ b/docs/how-to/regenerate-schemas.md @@ -3,9 +3,15 @@ The JSON schema files under `src/deploy_tools/models/schemas` are generated from the Pydantic models in `src/deploy_tools/models` by `deploy_tools.models.schema.generate_schema`. They are checked in and do not update -automatically, so after changing any model you must regenerate and commit them. +automatically, so they must be regenerated and committed after changing any model. -The simplest way is the **Generate Schema** VSCode task (see +A `generate-schema` pre-commit hook does this for you: when you commit a change to +any file under `src/deploy_tools/models`, it regenerates the schemas. If they changed, +pre-commit reports the modified files and aborts the commit, so you just `git add` the +schemas and commit again. + +If you bypass the hooks (for example with `git commit --no-verify`), regenerate the +schemas manually. The simplest way is the **Generate Schema** VSCode task (see [the VSCode tasks guide](vscode-tasks.md)), which writes to the correct location. Equivalently, run the CLI, pointing it at that folder: @@ -13,4 +19,5 @@ Equivalently, run the CLI, pointing it at that folder: deploy-tools schema src/deploy_tools/models/schemas ``` -Commit the regenerated files alongside your model change. +Either way, commit the regenerated files alongside your model change. CI fails if they +are out of date.