From 371d1086724e275963c5a42a795f58d8acaa71c0 Mon Sep 17 00:00:00 2001 From: Grigory Panov Date: Fri, 28 Aug 2026 10:40:24 +0200 Subject: [PATCH 1/8] 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 0000000000..e69eeb209f --- /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 228d955df59ea7668e8b3125f7caef40de5770b8 Mon Sep 17 00:00:00 2001 From: Grigory Panov Date: Fri, 28 Aug 2026 10:49:06 +0200 Subject: [PATCH 2/8] 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 e69eeb209f..b6a680bab8 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 34c62643f77394ae64ce447c64aa6916ef3e3459 Mon Sep 17 00:00:00 2001 From: Grigory Panov Date: Fri, 28 Aug 2026 10:56:18 +0200 Subject: [PATCH 3/8] 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 b6a680bab8..67a72f3249 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 2210ab001f58884da2f8f4b1c3bfab7aea72715f Mon Sep 17 00:00:00 2001 From: Grigory Panov Date: Fri, 28 Aug 2026 11:03:06 +0200 Subject: [PATCH 4/8] 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 67a72f3249..9b89cdd2e7 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 e7c8c86a249205781567f161aa1b0c9dc52db49b Mon Sep 17 00:00:00 2001 From: Grigory Panov Date: Fri, 28 Aug 2026 11:09:52 +0200 Subject: [PATCH 5/8] 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 9b89cdd2e7..98dfa0faa8 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 c9bc6ea5ca7fc1e13d2fa3e5a1cd8b68efee3dba Mon Sep 17 00:00:00 2001 From: Grigory Panov Date: Fri, 28 Aug 2026 11:11:50 +0200 Subject: [PATCH 6/8] 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 98dfa0faa8..e66d79b1dd 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 c633498153cc0166e388c95815d813354ab8f463 Mon Sep 17 00:00:00 2001 From: Grigory Panov Date: Fri, 28 Aug 2026 11:14:45 +0200 Subject: [PATCH 7/8] 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 e66d79b1dd..87eaf155dc 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 d6add1c1279ec53a6ef29724933454bc7fdc325c Mon Sep 17 00:00:00 2001 From: Grigory Panov Date: Fri, 28 Aug 2026 20:08:37 +0200 Subject: [PATCH 8/8] 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 87eaf155dc..0c9f946259 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.