Skip to content

Add orthogonal setup-local flags (--no-constraints, --no-dbconnect, --no-provision) and a skipped phase status - #6464

Open
rugpanov wants to merge 1 commit into
mainfrom
setup-local/orthogonal-flags
Open

Add orthogonal setup-local flags (--no-constraints, --no-dbconnect, --no-provision) and a skipped phase status#6464
rugpanov wants to merge 1 commit into
mainfrom
setup-local/orthogonal-flags

Conversation

@rugpanov

@rugpanov rugpanov commented Sep 1, 2026

Copy link
Copy Markdown
Contributor

Why

databricks environments setup-local had a single --constraints-only mode that
bundled "skip databricks-connect" together with the rest of the setup. A caller
that wants to write the project files but defer provisioning, or manage its own
dependency pins, had no way to express that. The setup steps are independent, so
the flags that control them should be too.

What

Three orthogonal, composable negative flags:

  • --no-constraints — skip writing the remote Python-version and dependency
    pins (requires-python and the [tool.uv] constraint block). Existing values
    are left untouched, and (when provisioning) the resolved Python is still
    installed — the flag only governs what is written.
  • --no-dbconnect — skip the databricks-connect dependency. Equivalent to
    the existing --constraints-only, which is left in place for now (either flag
    triggers the same behaviour).
  • --no-provision — write the project files through the merge phase, then
    stop: no Python download, uv sync, or validation. Because it never invokes
    uv, its preflight no longer requires or installs uv either, so a files-only run
    works on a machine without uv.

A new skipped phase status (distinct from pending, which means an earlier
phase failed) is reported for the provision and validate phases under
--no-provision; venvPath is omitted and the --dry-run plan drops
wouldInstallPython. The text summary gains a dedicated "provisioning skipped"
variant so it no longer prints an empty venv path or a broken activation hint.

The --no-constraints "unmanaged" signal is a nil ConstraintDeps / empty
requires-python. parseConstraints now normalizes a missing
[tool.uv].constraint-dependencies to a non-nil empty slice, so nil uniquely
means the flag rather than an artifact that simply omits the section.

Note on --no-constraints + provisioning

--no-constraints governs only what is written. A provisioning run still installs
and validates the resolved Python, so if a user's kept requires-python is
disjoint from the target, uv surfaces it as a normal E_PROVISION rather than the
command guessing an alternative. The --no-constraints --no-provision pairing
skips provisioning entirely and avoids that tension.

Backward compatibility

Default runs (no new flags) produce byte-for-byte identical output and behaviour
— every existing acceptance golden is unchanged except the refreshed --help
listing. The --output json schemaVersion stays at 1: the new skipped
status only ever appears when one of the new flags is passed.

Testing

  • Unit (libs/localenv): --no-provision writes files then skips
    provision/validate without invoking uv; --dry-run --no-provision marks them
    skipped and drops wouldInstallPython; --no-constraints leaves existing
    pins untouched and omits them greenfield; parseConstraints normalizes a
    missing constraint-dependencies; merge/render skip guards.
  • Acceptance (acceptance/localenv): new no-provision (real run),
    no-constraints, no-dbconnect, no-provision-dry-run, and
    no-provision-text goldens, plus the refreshed help output.
  • gofmt, go vet, and full go build ./... clean.

This pull request and its description were written by Isaac.

*Why*

`databricks environments setup-local` had a single `--constraints-only` mode
that bundled "skip databricks-connect" together with the rest of the setup. A
caller (the VS Code extension, agents) that wants to write project files but
defer provisioning, or manage its own dependency pins, had no way to express
that. The setup steps are independent, so the flags that control them should be
too.

*What*

Adds three orthogonal, composable negative flags:

- `--no-constraints` skips writing the remote Python-version and dependency
  pins (requires-python and the [tool.uv] constraint block); any existing values
  are left untouched, and provisioning still installs the resolved Python (the
  flag governs only what is written).
- `--no-dbconnect` skips the databricks-connect dependency. Equivalent to the
  existing `--constraints-only`, which stays as-is for now.
- `--no-provision` writes the project files through the merge phase, then stops:
  no Python download, uv sync, or validation. Because it never invokes uv, its
  preflight no longer requires or installs uv either — a files-only run works on
  a machine without uv.

Introduces a new `skipped` phase status (distinct from `pending`, which means an
earlier phase failed): the provision and validate phases report `skipped` under
`--no-provision`, `venvPath` is omitted, and the dry-run plan drops
`wouldInstallPython`. The text summary gains a dedicated "provisioning skipped"
variant so it no longer prints an empty venv path or a broken activation hint.

The `--no-constraints` "unmanaged" signal is a nil ConstraintDeps / empty
requires-python; parseConstraints now normalizes a missing
[tool.uv].constraint-dependencies to a non-nil empty slice so that nil uniquely
means the flag, not merely an artifact that omits the section.

Default runs (no new flags) are byte-for-byte unchanged; the JSON schemaVersion
stays at 1 since the new status only appears when a new flag is passed.

*Verification*

- Unit tests (libs/localenv): no-provision writes files then skips
  provision/validate without invoking uv, dry-run plus no-provision marks them
  skipped and drops wouldInstallPython, no-constraints leaves existing pins
  untouched and omits them greenfield, parseConstraints normalizes missing
  constraint-dependencies, and the merge/render skip guards.
- Acceptance goldens: no-provision (real run), no-constraints, no-dbconnect,
  no-provision-dry-run, no-provision-text, plus the refreshed help output.
- gofmt, go vet, and full go build ./... clean.

Co-authored-by: Isaac <no-reply@databricks.com>
@rugpanov
rugpanov force-pushed the setup-local/orthogonal-flags branch from 70c6da8 to d1aad7e Compare September 1, 2026 15:20
@rugpanov
rugpanov marked this pull request as ready for review September 1, 2026 15:45
@github-actions

github-actions Bot commented Sep 1, 2026

Copy link
Copy Markdown
Contributor

Approval status: pending

/acceptance/localenv/ - needs approval

21 files changed
Suggested: @anton-107
Also eligible: @rclarey, @misha-db

/cmd/environments/ - needs approval

Files: cmd/environments/output.go, cmd/environments/sync.go
Suggested: @anton-107
Also eligible: @rclarey, @misha-db

/libs/localenv/ - needs approval

7 files changed
Suggested: @anton-107
Also eligible: @rclarey, @misha-db

General files (require maintainer)

Files: .nextchanges/cli/setup-local-orthogonal-flags.md
Based on git history:

  • @janniklasrose -- recent work in .nextchanges/cli/

Any maintainer (@andrewnester, @anton-107, @denik, @pietern, @shreyas-goenka, @simonfaltum, @renaudhartert-db, @janniklasrose, @lennartkats-db, @rclarey) can approve all areas.
See OWNERS for ownership rules.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant