From 9de3e5090b872ba1bb4833e1e487aade5f670f15 Mon Sep 17 00:00:00 2001 From: Grigory Panov Date: Fri, 28 Aug 2026 10:40:24 +0200 Subject: [PATCH 1/9] Add bump-serverless-env-version skill Automates the serverless environment version bump across bundle templates: the serverless_environment_version macro plus the hardcoded literals in default-scala and lakeflow-integrations, the coupled Python / DB Connect pins in default/, golden regeneration across both template trees, and the mandatory verify pass. Delegates policy to .agents/rules/template-versions.md. Follow-up to #6378. Co-authored-by: Isaac --- .../bump-serverless-env-version/SKILL.md | 130 ++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 .agents/skills/bump-serverless-env-version/SKILL.md diff --git a/.agents/skills/bump-serverless-env-version/SKILL.md b/.agents/skills/bump-serverless-env-version/SKILL.md new file mode 100644 index 00000000000..e69eeb209fa --- /dev/null +++ b/.agents/skills/bump-serverless-env-version/SKILL.md @@ -0,0 +1,130 @@ +--- +name: bump-serverless-env-version +description: "Use when bumping the default serverless environment version in bundle templates, upgrading serverless env to a new version, or updating the coupled DB Connect / Python version pins in libs/template/templates/*/library/versions.tmpl." +user-invocable: true +allowed-tools: Read, Edit, Write, Bash, Glob, Grep, WebFetch, AskUserQuestion +--- + +# Bump the serverless environment version + +The DB Connect and Python pins a freshly initialized bundle project ships with +live in the `library/versions.tmpl` files under `libs/template/templates/`. The +serverless environment version lives in two forms — a `versions.tmpl` macro *and* +hardcoded literals in a few templates that don't reference the macro (Step 2). +`serverless_environment_version`, the Python pins, and the DB Connect pin form +one mutually compatible set; everything under `acceptance/` is rendered output +you regenerate, not hand-edit. + +**Read `.agents/rules/template-versions.md` first** — it holds the three RULES this +skill must obey (keep DB Connect at the lowest working pin, keep the version set +mutually compatible, sync `serverless_environment_version` across templates but +nothing else). This skill is the procedure; that doc is the policy. + +**Scope:** template pins only. The SSH serverless default (`environment_version: "4"` +in `acceptance/ssh/connect-serverless-*/output.txt`) is a separate hardcoded Go +default in `cmd/environments` / `libs/.../localenv`, not driven by templates — +leave it alone. + +## Steps + +**1. Resolve the target version and cross-check compatibility.** +Use the environment version the user gave, or the newest one on the +[serverless environment version release notes](https://docs.databricks.com/aws/en/release-notes/serverless/environment-version/). +An environment version dictates a runtime Python version, and the DB Connect pin +must support that Python, so resolve all three together: +- Confirm the target version exists and note the Python it ships against the + [databricks/environments](https://github.com/databricks/environments) repo (public — the + source of truth for each environment version's package set) and the release notes. +- Check the DB Connect pin against the + [DB Connect requirements](https://docs.databricks.com/dev-tools/databricks-connect/python/index.html#requirements). +- Apply the RULES in `.agents/rules/template-versions.md`. In particular, bump + `conservative_db_connect_version_spec` **only** when the currently pinned DBR + release has fallen out of support — not merely to match the new environment + version. + +**2. Apply the edits.** The environment version lives in two forms, so find every +occurrence first — bumping the macro alone silently misses the hardcoded ones: + +```bash +grep -rn 'environment_version\|environment-version' libs/template/templates/ +``` + +- **Macro** (`serverless_environment_version`): defined in + `default/library/versions.tmpl` and `dbt-sql/library/versions.tmpl`, referenced + by those templates' job/notebook files. Bump it in **both** files to the same + value. +- **Hardcoded literals**: these templates pin the version directly rather than + referencing the macro, so the macro bump does *not* reach them. Edit each to the + same target version: + - `default-scala/.../resources/{{.project_name}}.job.yml.tmpl` + - `lakeflow-integrations/.../databricks.yml.tmpl` (the `--environment-version` arg) + - `lakeflow-integrations/.../resources/send_slack_message.job.yml.tmpl` + - `lakeflow-integrations/.../resources/wait_for_run_sensor.job.yml.tmpl` + + (These literals not being wired to the macro is a known wart — the grep is your + safety net. Re-run it after editing and confirm every hit shows the new value.) +- In `default/` also bump `python_version_spec` / `default_python_version` if the + new environment version's Python changed, and + `conservative_db_connect_version_spec` only per the rule above. +- Do **not** sync other macros. `latest_lts_dbr_version` is intentionally `16.4` + in `default/` but `15.4` in the SQL templates, and each SQL template's + `latest_lts_db_connect_version_spec` is a distinct macro from `default/`'s + `conservative_db_connect_version_spec`. `default-sql/` does not ship a serverless + environment version at all. + +**3. Update the version comments.** +Each macro in `default/versions.tmpl` carries a comment block explaining the +compatibility reasoning (which Python the environment version uses, why DB +Connect is pinned where it is). Update those so the "why" matches the new pins. + +**4. Regenerate goldens across BOTH template trees, then VERIFY.** +Template output is rendered into two acceptance trees, and a bump changes both: +- `acceptance/bundle/templates/**` (default-python, dbt-sql, lakeflow-pipelines, …) +- `acceptance/pipelines/**` (pipelines init renders lakeflow-pipelines) + +`./task test-update-templates` regenerates only `bundle/templates` and misses +`pipelines`, so use the full update + verify pass instead: + +```bash +GOTOOLCHAIN=local go test ./acceptance -run '^TestAccept$' -update -timeout=60m +GOTOOLCHAIN=local go test ./acceptance -run '^TestAccept$' -timeout=60m # MUST pass on its own +``` + +The verify (non-update) pass is not optional. Bundle tests run under an +`EnvMatrix` of both engines (`terraform`, `direct`); with `-update` each variant +overwrites the other's `output.txt`, so a run can report `ok` on a golden that is +actually wrong. Only the non-update run catches this. (Ignore +`rejecting_proxy.go: blocking proxy` log lines — they are normal. A test that +times out under full parallel load but passes when run alone is a flake.) + +**5. Changelog fragment.** +Add a `bundles` fragment at `.nextchanges/bundles/serverless-environment-version-v{N}.md`, +modeled on the prior bump: + +``` +Bundle templates now use serverless [environment version {N}](https://docs.databricks.com/aws/en/release-notes/serverless/environment-version/{word}), which offers better performance, and `databricks-connect` {X.Y}. +``` + +See the `pr-checklist` skill's "Changelog entry" section for conventions. + +**6. Commit, push, PR.** +Run `./task fmt` and `./task lint-q` (if either touches `acceptance/`, a fixture +is wrong — fix the source, not the output). Commit and push; if the push 403s, +the active gh account lacks write access to `databricks/cli` (`gh auth switch`). +Then follow the `pr-checklist` skill for the commit body and PR description. +**Do not run `gh pr create` without the user's explicit permission.** + +Commit body and PR description: + +``` +## Changes + +Bump the default serverless environment version in bundle templates from {old} to {N}. + +- Python pinned to {python_spec} to match environment version {N} +- DB Connect pinned to {db_connect_spec} + +## Tests + +Acceptance goldens regenerated across bundle/templates and pipelines. +``` From b3e7cb9b2d14f78416ecdcaed32d4a3fe093f6c7 Mon Sep 17 00:00:00 2001 From: Grigory Panov Date: Fri, 28 Aug 2026 10:49:06 +0200 Subject: [PATCH 2/9] Address devil's-advocate review - Scope: defaultServerlessVersion (libs/localenv/envkey.go) is a separate "latest LTS" Go pin, not the SSH test fixture; tell the bumper to check and bump it in sync rather than "leave it alone". - Step 2: make the grep the source of truth; the file list is orientation only. Co-authored-by: Isaac --- .../bump-serverless-env-version/SKILL.md | 43 +++++++++++-------- 1 file changed, 24 insertions(+), 19 deletions(-) diff --git a/.agents/skills/bump-serverless-env-version/SKILL.md b/.agents/skills/bump-serverless-env-version/SKILL.md index e69eeb209fa..b6a680bab8a 100644 --- a/.agents/skills/bump-serverless-env-version/SKILL.md +++ b/.agents/skills/bump-serverless-env-version/SKILL.md @@ -20,10 +20,17 @@ skill must obey (keep DB Connect at the lowest working pin, keep the version set mutually compatible, sync `serverless_environment_version` across templates but nothing else). This skill is the procedure; that doc is the policy. -**Scope:** template pins only. The SSH serverless default (`environment_version: "4"` -in `acceptance/ssh/connect-serverless-*/output.txt`) is a separate hardcoded Go -default in `cmd/environments` / `libs/.../localenv`, not driven by templates — -leave it alone. +**Scope:** bundle template pins. Two related version pins live outside the +templates — check them, don't assume: +- `defaultServerlessVersion` in `libs/localenv/envkey.go` is a separate Go pin: the + fallback serverless version for `databricks environments setup-local`, documented + as a "stand-in for the latest LTS". It currently tracks the template version. If + the version you're moving to is the latest LTS, bump this constant in the same PR + and regenerate its tests (`libs/localenv`, `cmd/environments`); if it is not yet + LTS, leave it and say why. Do not silently ignore it. +- The SSH acceptance goldens (`acceptance/ssh/connect-serverless-*/output.txt`) pin + an explicit older version on purpose — a deliberate test fixture, not the + template default. Leave them alone. ## Steps @@ -42,27 +49,25 @@ must support that Python, so resolve all three together: release has fallen out of support — not merely to match the new environment version. -**2. Apply the edits.** The environment version lives in two forms, so find every -occurrence first — bumping the macro alone silently misses the hardcoded ones: +**2. Apply the edits.** The environment version lives in two forms — a macro and +hardcoded literals — so this grep, not any file list, is the source of truth for +what to change. Bumping the macro alone silently misses the literals: ```bash grep -rn 'environment_version\|environment-version' libs/template/templates/ ``` +Bring **every** hit to the target version, then re-run the grep and confirm each +one shows the new value. The hits fall into two kinds (paths below are what they +match today, for orientation — trust the grep if they've moved): - **Macro** (`serverless_environment_version`): defined in - `default/library/versions.tmpl` and `dbt-sql/library/versions.tmpl`, referenced - by those templates' job/notebook files. Bump it in **both** files to the same - value. -- **Hardcoded literals**: these templates pin the version directly rather than - referencing the macro, so the macro bump does *not* reach them. Edit each to the - same target version: - - `default-scala/.../resources/{{.project_name}}.job.yml.tmpl` - - `lakeflow-integrations/.../databricks.yml.tmpl` (the `--environment-version` arg) - - `lakeflow-integrations/.../resources/send_slack_message.job.yml.tmpl` - - `lakeflow-integrations/.../resources/wait_for_run_sensor.job.yml.tmpl` - - (These literals not being wired to the macro is a known wart — the grep is your - safety net. Re-run it after editing and confirm every hit shows the new value.) + `default/library/versions.tmpl` and `dbt-sql/library/versions.tmpl` and + referenced by those templates' job/notebook files. Editing the two `define`s + updates every reference. +- **Hardcoded literals**: templates that pin the version directly, so the macro + edit does *not* reach them — currently `default-scala`'s job template and three + `lakeflow-integrations` files (including a `--environment-version` CLI arg). Edit + each literal by hand. - In `default/` also bump `python_version_spec` / `default_python_version` if the new environment version's Python changed, and `conservative_db_connect_version_spec` only per the rule above. From b8addc930870d9361cb442e4c5b09ae7f2fe7f8f Mon Sep 17 00:00:00 2001 From: Grigory Panov Date: Fri, 28 Aug 2026 10:56:18 +0200 Subject: [PATCH 3/9] Address multi-source review findings - Remove GOTOOLCHAIN=local from the golden commands: env-specific, diverges from bump-sdk/bump-tf, and can break contributors on older local Go. - Step 6: defer PR body to pr-checklist + the PR template (Changes/Why/Tests in order + authorship disclosure) instead of a competing template that dropped ## Why; broaden pre-PR checks to fmt/checks/lint/test. - Step 2: only version-bearing grep hits get edited (macro names / template references carry no literal). - Step 5: spell out the release-notes URL slug convention (five/six). Co-authored-by: Isaac --- .../bump-serverless-env-version/SKILL.md | 54 ++++++++++--------- 1 file changed, 28 insertions(+), 26 deletions(-) diff --git a/.agents/skills/bump-serverless-env-version/SKILL.md b/.agents/skills/bump-serverless-env-version/SKILL.md index b6a680bab8a..67a72f3249e 100644 --- a/.agents/skills/bump-serverless-env-version/SKILL.md +++ b/.agents/skills/bump-serverless-env-version/SKILL.md @@ -57,9 +57,11 @@ what to change. Bumping the macro alone silently misses the literals: grep -rn 'environment_version\|environment-version' libs/template/templates/ ``` -Bring **every** hit to the target version, then re-run the grep and confirm each -one shows the new value. The hits fall into two kinds (paths below are what they -match today, for orientation — trust the grep if they've moved): +Inspect every hit and update each one that pins a version — the value in a macro +`define` or a hardcoded literal (many hits are the macro *name* or a `{{template +...}}` reference and carry no version to change). Then re-run the grep and confirm +every version-bearing hit shows the new value. The hits fall into two kinds (paths +below are what they match today, for orientation — trust the grep if they've moved): - **Macro** (`serverless_environment_version`): defined in `default/library/versions.tmpl` and `dbt-sql/library/versions.tmpl` and referenced by those templates' job/notebook files. Editing the two `define`s @@ -91,8 +93,8 @@ Template output is rendered into two acceptance trees, and a bump changes both: `pipelines`, so use the full update + verify pass instead: ```bash -GOTOOLCHAIN=local go test ./acceptance -run '^TestAccept$' -update -timeout=60m -GOTOOLCHAIN=local go test ./acceptance -run '^TestAccept$' -timeout=60m # MUST pass on its own +go test ./acceptance -run '^TestAccept$' -update -timeout=60m +go test ./acceptance -run '^TestAccept$' -timeout=60m # MUST pass on its own ``` The verify (non-update) pass is not optional. Bundle tests run under an @@ -107,29 +109,29 @@ Add a `bundles` fragment at `.nextchanges/bundles/serverless-environment-version modeled on the prior bump: ``` -Bundle templates now use serverless [environment version {N}](https://docs.databricks.com/aws/en/release-notes/serverless/environment-version/{word}), which offers better performance, and `databricks-connect` {X.Y}. +Bundle templates now use serverless [environment version {N}](https://docs.databricks.com/aws/en/release-notes/serverless/environment-version/{N-spelled-out}), which offers better performance, and `databricks-connect` {X.Y}. ``` -See the `pr-checklist` skill's "Changelog entry" section for conventions. +The release-notes URL ends in the version spelled out (`.../environment-version/five` +for 5, `six` for 6), matching the v5 fragment. See the `pr-checklist` skill's +"Changelog entry" section for conventions. **6. Commit, push, PR.** -Run `./task fmt` and `./task lint-q` (if either touches `acceptance/`, a fixture -is wrong — fix the source, not the output). Commit and push; if the push 403s, -the active gh account lacks write access to `databricks/cli` (`gh auth switch`). -Then follow the `pr-checklist` skill for the commit body and PR description. -**Do not run `gh pr create` without the user's explicit permission.** - -Commit body and PR description: - -``` -## Changes - -Bump the default serverless environment version in bundle templates from {old} to {N}. +Run the pre-PR checks from the `pr-checklist` skill — `./task fmt`, `./task checks`, +`./task lint`, `./task test` (the diff-only `-q` wrappers are not what CI runs). If +any check touches `acceptance/`, a fixture is wrong — fix the source, not the +output. Commit and push; if the push 403s, the active gh account lacks write access +to `databricks/cli` (`gh auth switch`). + +For the commit body and PR description, follow the `pr-checklist` skill and the PR +template exactly — fill all of `## Changes`, `## Why`, `## Tests` (in that order) +plus the agent-authorship disclosure line; do not drop a section. The bump-specific +content for those sections: +- **Changes**: `Bump the default serverless environment version in bundle templates + from {old} to {N}.`, then one bullet per coupled pin you moved — Python to + `{python_spec}`; DB Connect to `{db_connect_spec}` only if changed, stating why + per the DBR-support rule; and `defaultServerlessVersion` if you bumped it. +- **Tests**: acceptance goldens regenerated across `bundle/templates` and + `pipelines`, re-verified with the non-update pass. -- Python pinned to {python_spec} to match environment version {N} -- DB Connect pinned to {db_connect_spec} - -## Tests - -Acceptance goldens regenerated across bundle/templates and pipelines. -``` +**Do not run `gh pr create` without the user's explicit permission.** From b8415a2e5ce26129977d58bfe35afea48373d34c Mon Sep 17 00:00:00 2001 From: Grigory Panov Date: Fri, 28 Aug 2026 11:03:06 +0200 Subject: [PATCH 4/9] Address re-review findings (v2) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Scope: when bumping defaultServerlessVersion, also refresh the version shown in its help/example/error strings (cmd/environments/sync.go, libs/localenv/constraints.go), not just regenerate tests. - Step 5: don't extrapolate the changelog line from v5 — adapt the benefit to the target version's actual release notes and link its real URL. Co-authored-by: Isaac --- .../skills/bump-serverless-env-version/SKILL.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/.agents/skills/bump-serverless-env-version/SKILL.md b/.agents/skills/bump-serverless-env-version/SKILL.md index 67a72f3249e..9b89cdd2e77 100644 --- a/.agents/skills/bump-serverless-env-version/SKILL.md +++ b/.agents/skills/bump-serverless-env-version/SKILL.md @@ -25,8 +25,10 @@ templates — check them, don't assume: - `defaultServerlessVersion` in `libs/localenv/envkey.go` is a separate Go pin: the fallback serverless version for `databricks environments setup-local`, documented as a "stand-in for the latest LTS". It currently tracks the template version. If - the version you're moving to is the latest LTS, bump this constant in the same PR - and regenerate its tests (`libs/localenv`, `cmd/environments`); if it is not yet + the version you're moving to is the latest LTS, bump this constant in the same PR, + refresh the version shown in its help/example and error strings (grep `libs/localenv` + and `cmd/environments` for the old number — e.g. `cmd/environments/sync.go`, + `libs/localenv/constraints.go`), and regenerate the affected tests; if it is not yet LTS, leave it and say why. Do not silently ignore it. - The SSH acceptance goldens (`acceptance/ssh/connect-serverless-*/output.txt`) pin an explicit older version on purpose — a deliberate test fixture, not the @@ -106,14 +108,16 @@ times out under full parallel load but passes when run alone is a flake.) **5. Changelog fragment.** Add a `bundles` fragment at `.nextchanges/bundles/serverless-environment-version-v{N}.md`, -modeled on the prior bump: +modeled on the prior bump — but adapt the wording to the target version rather than +copying it: state the benefit its release notes actually call out (don't assert +"better performance" unless they do), and link its real release-notes URL: ``` -Bundle templates now use serverless [environment version {N}](https://docs.databricks.com/aws/en/release-notes/serverless/environment-version/{N-spelled-out}), which offers better performance, and `databricks-connect` {X.Y}. +Bundle templates now use serverless [environment version {N}]({release-notes-url}), which , and `databricks-connect` {X.Y}. ``` -The release-notes URL ends in the version spelled out (`.../environment-version/five` -for 5, `six` for 6), matching the v5 fragment. See the `pr-checklist` skill's +The URL historically ends in the version spelled out (`.../environment-version/five` +for 5, `six` for 6), but confirm the actual link. See the `pr-checklist` skill's "Changelog entry" section for conventions. **6. Commit, push, PR.** From 07f8cac6809ac271d5438655558ab4a2a9a96526 Mon Sep 17 00:00:00 2001 From: Grigory Panov Date: Fri, 28 Aug 2026 11:09:52 +0200 Subject: [PATCH 5/9] Fix Step 4 verify rationale (v3 review) The "-update lets both EnvMatrix variants overwrite each other's output" explanation is stale: -update now auto-enables -subset (acceptance_test.go), regenerating each output file from one covering variant. Correct the rationale (the non-update pass matters because it runs *every* variant against the goldens) and stop framing a load-induced timeout as an automatic flake. Co-authored-by: Isaac --- .../skills/bump-serverless-env-version/SKILL.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/.agents/skills/bump-serverless-env-version/SKILL.md b/.agents/skills/bump-serverless-env-version/SKILL.md index 9b89cdd2e77..98dfa0faa84 100644 --- a/.agents/skills/bump-serverless-env-version/SKILL.md +++ b/.agents/skills/bump-serverless-env-version/SKILL.md @@ -99,12 +99,14 @@ go test ./acceptance -run '^TestAccept$' -update -timeout=60m go test ./acceptance -run '^TestAccept$' -timeout=60m # MUST pass on its own ``` -The verify (non-update) pass is not optional. Bundle tests run under an -`EnvMatrix` of both engines (`terraform`, `direct`); with `-update` each variant -overwrites the other's `output.txt`, so a run can report `ok` on a golden that is -actually wrong. Only the non-update run catches this. (Ignore -`rejecting_proxy.go: blocking proxy` log lines — they are normal. A test that -times out under full parallel load but passes when run alone is a flake.) +The verify (non-update) pass is not optional. On `-update`, acceptance auto-enables +`-subset`, regenerating each output file from just one covering `EnvMatrix` variant +(`terraform` / `direct`); the plain non-update run then exercises *every* variant +against those goldens, so it is what catches a variant whose output diverges — the +update subset alone would not. It must pass on its own. (Ignore the normal +`rejecting_proxy.go: blocking proxy` log lines. If a test times out only under full +parallel load, re-run it in isolation to tell a load flake from a real regression — +don't wave off a test that fails deterministically.) **5. Changelog fragment.** Add a `bundles` fragment at `.nextchanges/bundles/serverless-environment-version-v{N}.md`, From 238ce2cfad9171cea47c0a6d44c11da0ea644d2d Mon Sep 17 00:00:00 2001 From: Grigory Panov Date: Fri, 28 Aug 2026 11:11:50 +0200 Subject: [PATCH 6/9] Tighten wording (v4 review) - Intro: only the golden output under acceptance/ is regenerated (acceptance/ also holds hand-maintained inputs), not "everything under acceptance/". - Step 3: use the full path libs/template/templates/default/library/versions.tmpl. Co-authored-by: Isaac --- .agents/skills/bump-serverless-env-version/SKILL.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.agents/skills/bump-serverless-env-version/SKILL.md b/.agents/skills/bump-serverless-env-version/SKILL.md index 98dfa0faa84..e66d79b1dd4 100644 --- a/.agents/skills/bump-serverless-env-version/SKILL.md +++ b/.agents/skills/bump-serverless-env-version/SKILL.md @@ -12,8 +12,8 @@ live in the `library/versions.tmpl` files under `libs/template/templates/`. The serverless environment version lives in two forms — a `versions.tmpl` macro *and* hardcoded literals in a few templates that don't reference the macro (Step 2). `serverless_environment_version`, the Python pins, and the DB Connect pin form -one mutually compatible set; everything under `acceptance/` is rendered output -you regenerate, not hand-edit. +one mutually compatible set; the golden output under `acceptance/` is regenerated +from these sources, not hand-edited. **Read `.agents/rules/template-versions.md` first** — it holds the three RULES this skill must obey (keep DB Connect at the lowest working pin, keep the version set @@ -82,7 +82,7 @@ below are what they match today, for orientation — trust the grep if they've m environment version at all. **3. Update the version comments.** -Each macro in `default/versions.tmpl` carries a comment block explaining the +Each macro in `default/library/versions.tmpl` carries a comment block explaining the compatibility reasoning (which Python the environment version uses, why DB Connect is pinned where it is). Update those so the "why" matches the new pins. From 14c6b163532671ed491e70fdaef342736e2131b0 Mon Sep 17 00:00:00 2001 From: Grigory Panov Date: Fri, 28 Aug 2026 11:14:45 +0200 Subject: [PATCH 7/9] Narrow Step 3 to the comments with compatibility reasoning (v5 review) Only the conservative_db_connect_version_spec and python_version_spec blocks carry version-specific reasoning; name them instead of implying every macro does. Co-authored-by: Isaac --- .agents/skills/bump-serverless-env-version/SKILL.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.agents/skills/bump-serverless-env-version/SKILL.md b/.agents/skills/bump-serverless-env-version/SKILL.md index e66d79b1dd4..87eaf155dca 100644 --- a/.agents/skills/bump-serverless-env-version/SKILL.md +++ b/.agents/skills/bump-serverless-env-version/SKILL.md @@ -82,9 +82,10 @@ below are what they match today, for orientation — trust the grep if they've m environment version at all. **3. Update the version comments.** -Each macro in `default/library/versions.tmpl` carries a comment block explaining the -compatibility reasoning (which Python the environment version uses, why DB -Connect is pinned where it is). Update those so the "why" matches the new pins. +The `conservative_db_connect_version_spec` and `python_version_spec` comment blocks +in `default/library/versions.tmpl` carry the compatibility reasoning — which Python +the environment version uses, why DB Connect is pinned where it is. Update whichever +you touch so the "why" matches the new pins. **4. Regenerate goldens across BOTH template trees, then VERIFY.** Template output is rendered into two acceptance trees, and a bump changes both: From 4bc5e84e6bd9c22a499bc5719d01a47025503783 Mon Sep 17 00:00:00 2001 From: Grigory Panov Date: Fri, 28 Aug 2026 20:08:37 +0200 Subject: [PATCH 8/9] Refine serverless environment bump skill Narrow the trigger, target golden regeneration, separate the localenv fallback, and cross-check prior template bumps while keeping the workflow concise. Co-authored-by: Codex --- .../bump-serverless-env-version/SKILL.md | 215 ++++++++---------- 1 file changed, 91 insertions(+), 124 deletions(-) diff --git a/.agents/skills/bump-serverless-env-version/SKILL.md b/.agents/skills/bump-serverless-env-version/SKILL.md index 87eaf155dca..0c9f946259d 100644 --- a/.agents/skills/bump-serverless-env-version/SKILL.md +++ b/.agents/skills/bump-serverless-env-version/SKILL.md @@ -1,144 +1,111 @@ --- name: bump-serverless-env-version -description: "Use when bumping the default serverless environment version in bundle templates, upgrading serverless env to a new version, or updating the coupled DB Connect / Python version pins in libs/template/templates/*/library/versions.tmpl." +description: "Use when bumping or upgrading the default serverless environment version shipped by Databricks bundle templates, including its coupled Python and DB Connect pins." user-invocable: true allowed-tools: Read, Edit, Write, Bash, Glob, Grep, WebFetch, AskUserQuestion --- # Bump the serverless environment version -The DB Connect and Python pins a freshly initialized bundle project ships with -live in the `library/versions.tmpl` files under `libs/template/templates/`. The -serverless environment version lives in two forms — a `versions.tmpl` macro *and* -hardcoded literals in a few templates that don't reference the macro (Step 2). -`serverless_environment_version`, the Python pins, and the DB Connect pin form -one mutually compatible set; the golden output under `acceptance/` is regenerated -from these sources, not hand-edited. - -**Read `.agents/rules/template-versions.md` first** — it holds the three RULES this -skill must obey (keep DB Connect at the lowest working pin, keep the version set -mutually compatible, sync `serverless_environment_version` across templates but -nothing else). This skill is the procedure; that doc is the policy. - -**Scope:** bundle template pins. Two related version pins live outside the -templates — check them, don't assume: -- `defaultServerlessVersion` in `libs/localenv/envkey.go` is a separate Go pin: the - fallback serverless version for `databricks environments setup-local`, documented - as a "stand-in for the latest LTS". It currently tracks the template version. If - the version you're moving to is the latest LTS, bump this constant in the same PR, - refresh the version shown in its help/example and error strings (grep `libs/localenv` - and `cmd/environments` for the old number — e.g. `cmd/environments/sync.go`, - `libs/localenv/constraints.go`), and regenerate the affected tests; if it is not yet - LTS, leave it and say why. Do not silently ignore it. -- The SSH acceptance goldens (`acceptance/ssh/connect-serverless-*/output.txt`) pin - an explicit older version on purpose — a deliberate test fixture, not the - template default. Leave them alone. - -## Steps - -**1. Resolve the target version and cross-check compatibility.** -Use the environment version the user gave, or the newest one on the -[serverless environment version release notes](https://docs.databricks.com/aws/en/release-notes/serverless/environment-version/). -An environment version dictates a runtime Python version, and the DB Connect pin -must support that Python, so resolve all three together: -- Confirm the target version exists and note the Python it ships against the - [databricks/environments](https://github.com/databricks/environments) repo (public — the - source of truth for each environment version's package set) and the release notes. -- Check the DB Connect pin against the - [DB Connect requirements](https://docs.databricks.com/dev-tools/databricks-connect/python/index.html#requirements). -- Apply the RULES in `.agents/rules/template-versions.md`. In particular, bump - `conservative_db_connect_version_spec` **only** when the currently pinned DBR - release has fallen out of support — not merely to match the new environment - version. - -**2. Apply the edits.** The environment version lives in two forms — a macro and -hardcoded literals — so this grep, not any file list, is the source of truth for -what to change. Bumping the macro alone silently misses the literals: +Read `.agents/rules/template-versions.md` first for compatibility and +synchronization policy. Never hand-edit generated acceptance output. + +## 1. Resolve a compatible version set + +Use the requested environment version, or the newest published version when none +was specified. Confirm its runtime Python version from the +[environment release notes](https://docs.databricks.com/aws/en/release-notes/serverless/environment-version/) +and [databricks/environments](https://github.com/databricks/environments). + +Apply `.agents/rules/template-versions.md` to the environment, Python, and DB +Connect pins. Check Python compatibility in the +[DB Connect requirements](https://docs.databricks.com/dev-tools/databricks-connect/python/index.html#requirements). +Advance `conservative_db_connect_version_spec` only when its DBR line is no longer +supported, using the supported-LTS table in the +[Databricks Runtime release notes](https://docs.databricks.com/aws/en/release-notes/runtime/). +Do not advance it merely to match the environment version. + +## 2. Update every template source + +Find both macro definitions and hardcoded literals; trust the search results: ```bash grep -rn 'environment_version\|environment-version' libs/template/templates/ ``` -Inspect every hit and update each one that pins a version — the value in a macro -`define` or a hardcoded literal (many hits are the macro *name* or a `{{template -...}}` reference and carry no version to change). Then re-run the grep and confirm -every version-bearing hit shows the new value. The hits fall into two kinds (paths -below are what they match today, for orientation — trust the grep if they've moved): -- **Macro** (`serverless_environment_version`): defined in - `default/library/versions.tmpl` and `dbt-sql/library/versions.tmpl` and - referenced by those templates' job/notebook files. Editing the two `define`s - updates every reference. -- **Hardcoded literals**: templates that pin the version directly, so the macro - edit does *not* reach them — currently `default-scala`'s job template and three - `lakeflow-integrations` files (including a `--environment-version` CLI arg). Edit - each literal by hand. -- In `default/` also bump `python_version_spec` / `default_python_version` if the - new environment version's Python changed, and - `conservative_db_connect_version_spec` only per the rule above. -- Do **not** sync other macros. `latest_lts_dbr_version` is intentionally `16.4` - in `default/` but `15.4` in the SQL templates, and each SQL template's - `latest_lts_db_connect_version_spec` is a distinct macro from `default/`'s - `conservative_db_connect_version_spec`. `default-sql/` does not ship a serverless - environment version at all. - -**3. Update the version comments.** -The `conservative_db_connect_version_spec` and `python_version_spec` comment blocks -in `default/library/versions.tmpl` carry the compatibility reasoning — which Python -the environment version uses, why DB Connect is pinned where it is. Update whichever -you touch so the "why" matches the new pins. - -**4. Regenerate goldens across BOTH template trees, then VERIFY.** -Template output is rendered into two acceptance trees, and a bump changes both: -- `acceptance/bundle/templates/**` (default-python, dbt-sql, lakeflow-pipelines, …) -- `acceptance/pipelines/**` (pipelines init renders lakeflow-pipelines) - -`./task test-update-templates` regenerates only `bundle/templates` and misses -`pipelines`, so use the full update + verify pass instead: +Inspect every hit and change only values that pin a version. Re-run the command +after editing and confirm every version-bearing template hit uses the target. +If all sources and coupled pins already match the resolved set and the worktree has +no partial bump, report that no changes are needed and stop. + +Current sources include: + +- `serverless_environment_version` definitions in `default/library/versions.tmpl` + and `dbt-sql/library/versions.tmpl`; +- a hardcoded value in the `default-scala` job template; +- three hardcoded values in `lakeflow-integrations`, including its + `--environment-version` argument. + +In `default/library/versions.tmpl`, update `python_version_spec` and +`default_python_version` when the runtime Python version changes. Update +`conservative_db_connect_version_spec` only under the support rule above. Keep the +version-specific compatibility comments accurate even when their pin is unchanged. +Do not synchronize unrelated DBR or SQL-template DB Connect macros. + +Update version-specific examples in `.agents/rules/template-versions.md` so its +policy remains accurate; do not change the policy itself as part of the bump. + +Also inspect `defaultServerlessVersion` in `libs/localenv/envkey.go`. It is the +product-spec fallback for `databricks environments setup-local`, not a template +pin; do not infer that it should move with the templates. Change it only when the +user or current product specification also requires the fallback to move, and first +confirm `python/serverless/serverless-v{N}/pyproject.toml` exists in +`databricks/environments`. Then update default-version help, error, and test +expectations under `libs/localenv` and `cmd/environments`; verify with +`go test ./libs/localenv ./cmd/environments`, then update and verify with: ```bash -go test ./acceptance -run '^TestAccept$' -update -timeout=60m -go test ./acceptance -run '^TestAccept$' -timeout=60m # MUST pass on its own +go test ./acceptance -run '^TestAccept/localenv' -update -timeout=60m +go test ./acceptance -run '^TestAccept/localenv' -timeout=60m ``` -The verify (non-update) pass is not optional. On `-update`, acceptance auto-enables -`-subset`, regenerating each output file from just one covering `EnvMatrix` variant -(`terraform` / `direct`); the plain non-update run then exercises *every* variant -against those goldens, so it is what catches a variant whose output diverges — the -update subset alone would not. It must pass on its own. (Ignore the normal -`rejecting_proxy.go: blocking proxy` log lines. If a test times out only under full -parallel load, re-run it in isolation to tell a load flake from a real regression — -don't wave off a test that fails deterministically.) - -**5. Changelog fragment.** -Add a `bundles` fragment at `.nextchanges/bundles/serverless-environment-version-v{N}.md`, -modeled on the prior bump — but adapt the wording to the target version rather than -copying it: state the benefit its release notes actually call out (don't assert -"better performance" unless they do), and link its real release-notes URL: +Otherwise leave it unchanged and record why. Do not change the intentionally older +SSH fixtures in `acceptance/ssh/connect-serverless-*`. +## 3. Regenerate and verify targeted goldens + +Update and verify both template acceptance trees: + +```bash +./task test-update-templates +go test ./acceptance -run '^TestAccept/pipelines' -update -timeout=60m + +go test ./acceptance -run '^TestAccept/bundle/templates' -timeout=60m +go test ./acceptance -run '^TestAccept/pipelines' -timeout=60m ``` -Bundle templates now use serverless [environment version {N}]({release-notes-url}), which , and `databricks-connect` {X.Y}. -``` -The URL historically ends in the version spelled out (`.../environment-version/five` -for 5, `six` for 6), but confirm the actual link. See the `pr-checklist` skill's -"Changelog entry" section for conventions. - -**6. Commit, push, PR.** -Run the pre-PR checks from the `pr-checklist` skill — `./task fmt`, `./task checks`, -`./task lint`, `./task test` (the diff-only `-q` wrappers are not what CI runs). If -any check touches `acceptance/`, a fixture is wrong — fix the source, not the -output. Commit and push; if the push 403s, the active gh account lacks write access -to `databricks/cli` (`gh auth switch`). - -For the commit body and PR description, follow the `pr-checklist` skill and the PR -template exactly — fill all of `## Changes`, `## Why`, `## Tests` (in that order) -plus the agent-authorship disclosure line; do not drop a section. The bump-specific -content for those sections: -- **Changes**: `Bump the default serverless environment version in bundle templates - from {old} to {N}.`, then one bullet per coupled pin you moved — Python to - `{python_spec}`; DB Connect to `{db_connect_spec}` only if changed, stating why - per the DBR-support rule; and `defaultServerlessVersion` if you bumped it. -- **Tests**: acceptance goldens regenerated across `bundle/templates` and - `pipelines`, re-verified with the non-update pass. - -**Do not run `gh pr create` without the user's explicit permission.** +Both non-update commands must pass. Update mode selects covering `EnvMatrix` +variants; the non-update runs verify every variant against the regenerated goldens. + +## 4. Add the changelog fragment + +Add `.nextchanges/bundles/serverless-environment-version-v{N}.md`. Follow the +`pr-checklist` skill's changelog conventions. Describe a benefit stated in the +target version's release notes, link the actual version page, and mention the DB +Connect version only if it changed. + +Cross-check the final source and generated-output footprint against the prior +template bumps in [PR #3897](https://github.com/databricks/cli/pull/3897) and +[PR #6378](https://github.com/databricks/cli/pull/6378). Explain material +differences in the final handoff or PR description. Prior PRs are not sources of +truth: revalidate their compatibility decisions, wording, URLs, and file lists. + +## 5. Finish only when requested + +**Required sub-skill:** use `pr-checklist`, run its checks, and inspect the final +diff. If formatting or linting changes generated acceptance files, fix the source +and regenerate them. + +Commit, push, or create/update a PR only when the user explicitly requests that +operation. When requested, follow `pr-checklist` rather than duplicating its commit +and PR-body instructions here. From ef72ef0c4ac29c02dd9ddb35df8a362a00c22c63 Mon Sep 17 00:00:00 2001 From: Grigory Panov Date: Fri, 11 Sep 2026 15:08:49 +0200 Subject: [PATCH 9/9] Address serverless bump skill review Add compatibility and support-buffer rules, include Python pins in discovery, and identify the suggested reviewer. Co-authored-by: Codex --- .agents/rules/template-versions.md | 2 +- .../bump-serverless-env-version/SKILL.md | 32 +++++++++---------- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/.agents/rules/template-versions.md b/.agents/rules/template-versions.md index cd0c4b2b64f..f9b24120819 100644 --- a/.agents/rules/template-versions.md +++ b/.agents/rules/template-versions.md @@ -18,7 +18,7 @@ Bundle templates pin the runtime versions they render. Most pins are macros in ` **RULE: Keep the serverless environment version, the Python pins, the DB Connect pin, and `latest_lts_dbr_version` mutually compatible. This is a hard constraint.** A serverless environment version dictates a runtime Python version, and the DB Connect pin must support that Python. The DBR LTS pin belongs in the same check rather than being treated as independent — the two have drifted before: `latest_lts_dbr_version` reached 16.4 in #3671 while the DB Connect pin stayed on 15.4 until #6378. Cross-check the [serverless environment version release notes](https://docs.databricks.com/aws/en/release-notes/serverless/environment-version/) and the [DB Connect requirements](https://docs.databricks.com/dev-tools/databricks-connect/python/index.html#requirements) whenever you change any of the four. -**RULE: Within that constraint, keep `default`'s `conservative_db_connect_version_spec` as low as compatibility allows.** The DB Connect client is only forward-compatible (it reaches compute of its own version and higher), so the lowest compatible pin maximizes the range of DBR versions a customer can connect to; a higher pin rules out customers on older DBR, and they can move to a newer version themselves after initializing the template. The floor is the *oldest* release that passes two tests: it is still supported, *and* the DBR version it targets runs `python_version_spec`'s Python on the cluster — not merely that the client supports that Python. Support status only rules out the short-lived non-LTS releases; an LTS stays supported for years, so older LTS releases are ruled out by the runtime test instead. DB Connect 15.4 is the worked example: it is still supported and its client supports Python 3.12, but DBR 15 clusters run Python 3.11, so it fails the second test and 16.4 is the floor. Never read this as "pin the current DBR LTS" — that is the newest release, the opposite of a floor, and #6378 rejected exactly that bump. Keep the upper bound at the next minor release, so the spec stays inside one minor: widening it lets a freshly initialized project resolve a client far newer than the floor advertises, which is the opposite of conservative. Do not raise the pin merely to match a newer serverless environment version — raise it only when the constraint above forces it, or when the pinned release falls out of support (see the [DBR release notes](https://docs.databricks.com/aws/en/release-notes/runtime/) for supported versions). See PR #3897 and PR #6378 for prior history. +**RULE: Within that constraint, keep `default`'s `conservative_db_connect_version_spec` as low as compatibility allows.** The DB Connect client is only forward-compatible (it reaches compute of its own version and higher), so the lowest compatible pin maximizes the range of DBR versions a customer can connect to; a higher pin rules out customers on older DBR, and they can move to a newer version themselves after initializing the template. The floor is the *oldest* release that passes two tests: its DBR line has more than six months of support remaining, *and* the DBR version it targets runs `python_version_spec`'s Python on the cluster — not merely that the client supports that Python. The support buffer prevents freshly generated projects from immediately approaching end of support. DB Connect 15.4 is the worked example: its client supports Python 3.12, but DBR 15 clusters run Python 3.11, so it fails the second test and 16.4 is the floor. Never read this as "pin the current DBR LTS" — that is the newest release, the opposite of a floor, and #6378 rejected exactly that bump. Keep the upper bound at the next minor release, so the spec stays inside one minor: widening it lets a freshly initialized project resolve a client far newer than the floor advertises, which is the opposite of conservative. Do not raise the pin merely to match a newer serverless environment version — raise it only when the constraint above forces it, or when the pinned DBR line has six months or less of support remaining. Use the [DBR release notes](https://docs.databricks.com/aws/en/release-notes/runtime/) to choose the oldest compatible replacement with more than six months of support remaining. See PR #3897 and PR #6378 for prior history. This rule governs `default`'s pin. `default-scala` deliberately does the opposite: it tracks the newest LTS in `dbr_version` and derives its client from that macro in `template/{{.project_name}}/build.sbt.tmpl` as an open-ended `.+` dependency. Do not lower `dbr_version`, or pin that dependency, to satisfy the rule above. diff --git a/.agents/skills/bump-serverless-env-version/SKILL.md b/.agents/skills/bump-serverless-env-version/SKILL.md index 0c9f946259d..3fe6340ab5e 100644 --- a/.agents/skills/bump-serverless-env-version/SKILL.md +++ b/.agents/skills/bump-serverless-env-version/SKILL.md @@ -20,9 +20,10 @@ and [databricks/environments](https://github.com/databricks/environments). Apply `.agents/rules/template-versions.md` to the environment, Python, and DB Connect pins. Check Python compatibility in the [DB Connect requirements](https://docs.databricks.com/dev-tools/databricks-connect/python/index.html#requirements). -Advance `conservative_db_connect_version_spec` only when its DBR line is no longer -supported, using the supported-LTS table in the -[Databricks Runtime release notes](https://docs.databricks.com/aws/en/release-notes/runtime/). +Advance `conservative_db_connect_version_spec` when compatibility requires it or its +DBR line has six months or less of support remaining. Use the supported-LTS table in +the [Databricks Runtime release notes](https://docs.databricks.com/aws/en/release-notes/runtime/) +to choose the oldest compatible replacement with more than six months of support remaining. Do not advance it merely to match the environment version. ## 2. Update every template source @@ -30,7 +31,7 @@ Do not advance it merely to match the environment version. Find both macro definitions and hardcoded literals; trust the search results: ```bash -grep -rn 'environment_version\|environment-version' libs/template/templates/ +grep -rn 'environment_version\|environment-version\|requires-python\|default_python_version' libs/template/templates/ ``` Inspect every hit and change only values that pin a version. Re-run the command @@ -48,9 +49,9 @@ Current sources include: In `default/library/versions.tmpl`, update `python_version_spec` and `default_python_version` when the runtime Python version changes. Update -`conservative_db_connect_version_spec` only under the support rule above. Keep the -version-specific compatibility comments accurate even when their pin is unchanged. -Do not synchronize unrelated DBR or SQL-template DB Connect macros. +`conservative_db_connect_version_spec` only under the compatibility and support rule +above. Keep the version-specific compatibility comments accurate even when their pin +is unchanged. Do not synchronize unrelated DBR or SQL-template DB Connect macros. Update version-specific examples in `.agents/rules/template-versions.md` so its policy remains accurate; do not change the policy itself as part of the bump. @@ -72,20 +73,17 @@ go test ./acceptance -run '^TestAccept/localenv' -timeout=60m Otherwise leave it unchanged and record why. Do not change the intentionally older SSH fixtures in `acceptance/ssh/connect-serverless-*`. -## 3. Regenerate and verify targeted goldens +## 3. Regenerate and verify goldens -Update and verify both template acceptance trees: +Update and verify the acceptance suite: ```bash -./task test-update-templates -go test ./acceptance -run '^TestAccept/pipelines' -update -timeout=60m - -go test ./acceptance -run '^TestAccept/bundle/templates' -timeout=60m -go test ./acceptance -run '^TestAccept/pipelines' -timeout=60m +./task test-update +go test ./acceptance -run '^TestAccept$' -timeout=60m ``` -Both non-update commands must pass. Update mode selects covering `EnvMatrix` -variants; the non-update runs verify every variant against the regenerated goldens. +The non-update command must pass. Update mode selects covering `EnvMatrix` variants; +the non-update run verifies every variant against the regenerated goldens. ## 4. Add the changelog fragment @@ -109,3 +107,5 @@ and regenerate them. Commit, push, or create/update a PR only when the user explicitly requests that operation. When requested, follow `pr-checklist` rather than duplicating its commit and PR-body instructions here. + +When creating a PR for the bump, suggest `lennartkats-db` as a reviewer.