Repository navigation
air: remove stale Public Preview label from CLI help - #7502
Merged
Merged
Conversation
caroline-db
force-pushed
the
air-ga-help
branch
from
November 11, 2026 18:42
418c1c5 to
68f465a
Compare
Contributor
|
Commit: Regression test reportSelected 1 changed tests (limit=20, 0 not selected) 1 tests: regression=1 unreleased=0 coverage=0 failing=0
TestAccept/help: branch ✅ | main (4eeacdb) ❌ | latest (v1.26.0) ❌main (4eeacdb): latest (v1.26.0): same output as main (4eeacdb) |
caroline-db
force-pushed
the
air-ga-help
branch
from
November 11, 2026 18:51
68f465a to
d35e09e
Compare
stevenchen-db
approved these changes
Nov 11, 2026
Collaborator
✅ Integration test reportCommit: d35e09e
Top 19 slowest tests (at least 2 minutes):
|
caroline-db
enabled auto-merge
November 11, 2026 19:25
caroline-db
disabled auto-merge
November 11, 2026 19:25
pietern
approved these changes
Nov 11, 2026
github-merge-queue
Bot
removed this pull request from the merge queue due to no response for status checks
Nov 11, 2026
Collaborator
❌ Integration test reportCommit: 78702d5
62 interesting tests: 50 FAIL, 8 RECOVERED, 4 KNOWN
Top 50 slowest tests (at least 2 minutes):
|
idelafuente-oc
pushed a commit
to idelafuente-oc/cli
that referenced
this pull request
Nov 14, 2026
…bricks#7512) ## Changes Reorganize the `databricks air` help pages around the run lifecycle: - `air -h`: subcommands are grouped under **Run workloads**, **Manage runs**, **Package and deploy**, and **Provisioned capacity** instead of one A→Z list. Adds a two-line intro and a "Learn more" footer (YAML fields and example, AWS/Azure quickstart, agent skill). Drops "under active development" (databricks#7502 already removed the "Public Preview" label). - `air run -h`: adds Examples (`--watch`, `--dry-run`, `--override`) and lists flags most-used first. - `air run -h config`: adds a minimal YAML example and lists fields by purpose under Workload / Execution / MLflow tracking / Access and cost attribution, using a new `group` struct tag. Required fields come first in each group and are marked inline. The agent-skill instructions move below the field list, and the `air -h` footer also points to the skill. - `air run -h config.compute`: `pool_id` and `priority_class` move under "Provisioned capacity (optional)". - Required markers now match validation: `command` shows "(required unless containers is set)", `compute.num_accelerators` / `compute.accelerator_type` are marked required (they previously showed `Required: no`), and conditional requirements show inline, e.g. `code_source.root_path` "(required when code_source is set)". - `environment.version` help gives examples of both forms (`6`, `databricks_ai_v6`), says what the Standard and Databricks AI environments contain, and links the AI Runtime environment page (which lists supported versions) instead of the general serverless release notes. - Field help lists docs links for both AWS and Azure in a "Docs:" section (new `docs` struct tag with the path both clouds share) instead of AWS-only inline links. Applies to `environment.version`, `compute.num_accelerators`, and `compute.accelerator_type`. - Field-help hints are full commands (`databricks air run -h config.compute.accelerator_type`) instead of bare paths. - Wording pass on short descriptions ("workload", not "training workload"; "AI Runtime", not "AIR"; `YAML_PATH`; shorter `pools get`), help text names full commands (`databricks air run`, not `air run`), and usage-policy help says "attribute the run's usage to" instead of "bill the run to", matching the usage-policy docs. ### Before / after Taken from the acceptance golden files; the GPU list in `config.compute` comes from the test stub. Global Flags are unchanged and omitted. <details open><summary><code>databricks air -h</code></summary> **Before** ``` Run and manage AI Runtime training workloads on Databricks serverless GPU compute. These commands are under active development. Usage: databricks air [command] Available Commands: cancel Cancel one or more runs convert-to-dabs Convert an AIR run YAML into a Databricks Asset Bundle get Show status, configuration, and timing details for a specified run images Manage container images for AI Runtime list List active runs for the current user logs Stream or fetch logs for a run pools View provisioned GPU pools run Submit a training workload from a YAML config Flags: -h, --help help for air Use "databricks air [command] --help" for more information about a command. ``` **After** ``` Run GPU workloads on Databricks serverless compute. Describe a workload in a YAML file and submit it with "databricks air run". Follow a run with "databricks air logs" and "databricks air get", or see your active runs with "databricks air list". Usage: databricks air [command] Run workloads: run Submit a workload from a YAML config Manage runs: cancel Cancel one or more runs get Show a run's status, configuration, and timing list List your active runs logs Stream or fetch a run's logs Package and deploy: convert-to-dabs Convert a workload YAML into a Databricks Asset Bundle images Push container images for custom environments Provisioned capacity: pools View GPU pools provisioned for your workspace Flags: -h, --help help for air Use "databricks air [command] --help" for more information about a command. Learn more: YAML fields and example databricks air run -h config Quickstart (AWS) https://docs.databricks.com/aws/en/machine-learning/ai-runtime/quickstart Quickstart (Azure) https://learn.microsoft.com/azure/databricks/machine-learning/ai-runtime/quickstart Coding agent skill databricks aitools install --skills-only --skills databricks-ai-runtime ``` </details> <details><summary><code>databricks air run -h</code></summary> **Before** ``` Submit a training workload to Databricks serverless GPU compute. The workload is described by a YAML config file (see --file). To look up a config field, pass its path to -h: databricks air run -h config databricks air run -h config.compute databricks air run -h config.compute.accelerator_type The path must be a separate argument: cobra reserves -h as a boolean, so -h=config.compute and -hconfig.compute are not accepted. Usage: databricks air run [flags] Flags: --dry-run Validate the config against the workspace without submitting a run -f, --file string Path to the workload YAML config -h, --help help for run --idempotency-key string Return the existing run if this key was already used --override stringArray Override a YAML field, e.g. compute.num_accelerators=8 (repeatable) --watch Stream logs until the run completes ``` **After** ``` Submit a workload to Databricks serverless GPU compute. The workload is described by a YAML file (see --file). To look up a YAML field, pass its path to -h as a separate argument: databricks air run -h config all fields databricks air run -h config.compute one section databricks air run -h config.compute.accelerator_type one field Usage: databricks air run [flags] Examples: # Submit and stream logs until the run finishes databricks air run -f workload.yaml --watch # Validate the config against the workspace without submitting databricks air run -f workload.yaml --dry-run # Try a different GPU without editing the file databricks air run -f workload.yaml --override compute.accelerator_type=GPU_1xH100 Flags: -f, --file string Path to the workload YAML config --watch Stream logs until the run completes --override stringArray Override a YAML field, e.g. compute.num_accelerators=8 (repeatable) --dry-run Validate the config against the workspace without submitting a run --idempotency-key string Return the existing run if this key was already used -h, --help help for run ``` </details> <details><summary><code>databricks air run -h config</code></summary> **Before** ``` config The run YAML schema. Pass a field path for details, e.g. config.compute.accelerator_type. AI coding agents can use the databricks-ai-runtime skill to write workload YAML, submit runs, and monitor progress. Install the skill locally for your coding agent: databricks aitools install --skills-only --skills databricks-ai-runtime Follow the prompts to choose your coding agent and installation scope. Use --scope project to install into the current project. See: https://github.com/databricks/databricks-agent-skills/tree/main/skills/databricks-ai-runtime Fields: experiment_name (required) Name of the experiment. compute (required) Which accelerators to run on and how many. environment Python dependencies, runtime version, or a Unity Catalog image for a single-command run. command Shell command that starts the workload. containers Rank-partitioned containers for heterogeneous workloads. env_variables Plain environment variables, as NAME: value. secrets Environment variables sourced from secrets, as NAME: scope/key. code_source Local code to upload and make available to the run. max_retries How many times to retry a failed run. timeout_minutes Wall-clock limit for the run in minutes. idempotency_token Reuse token: a repeat submission with the same token returns the existing run instead of starting another. parameters Free-form values passed through to the workload. mlflow_run_name Name for the MLflow run. mlflow_experiment_directory Workspace directory holding the MLflow experiment. mlflow_artifact_location DBFS location where MLflow artifacts are written. permissions Who may view or manage the run, as a list of principal plus level grants. usage_policy_name Usage policy to bill the run to, by name. usage_policy_id Usage policy to bill the run to, by id. Use "-h config.<field>" for details on a field. ``` **After** ``` config Workload YAML schema. For details on a field, pass its path to -h, for example: databricks air run -h config.compute.accelerator_type Minimal example: experiment_name: my-run compute: num_accelerators: 1 accelerator_type: GPU_1xA10 code_source: root_path: . command: python "$CODE_SOURCE_PATH/train.py" Workload: experiment_name (required) Name of the experiment. compute (required) Which accelerators to run on and how many. command (required unless containers is set) Shell command that starts the workload. environment Python dependencies, runtime version, or a Unity Catalog image for a single-command run. containers Rank-partitioned containers for heterogeneous workloads. env_variables Plain environment variables, as NAME: value. secrets Environment variables sourced from secrets, as NAME: scope/key. code_source Local code to upload and make available to the run. parameters Free-form values passed through to the workload. Execution: max_retries How many times to retry a failed run. timeout_minutes Wall-clock limit for the run in minutes. idempotency_token Reuse token: a repeat submission with the same token returns the existing run instead of starting another. MLflow tracking: mlflow_run_name Name for the MLflow run. mlflow_experiment_directory Workspace directory holding the MLflow experiment. mlflow_artifact_location DBFS location where MLflow artifacts are written. Access and cost attribution: permissions Who may view or manage the run, as a list of principal plus level grants. usage_policy_name Usage policy to attribute the run's usage to, by name. usage_policy_id Usage policy to attribute the run's usage to, by id. For details on a field, run "databricks air run -h config.<field>". Let a coding agent write this YAML for you with the databricks-ai-runtime skill: databricks aitools install --skills-only --skills databricks-ai-runtime (add --scope project to install into the current project) https://github.com/databricks/databricks-agent-skills/tree/main/skills/databricks-ai-runtime ``` </details> <details><summary><code>databricks air run -h config.compute</code></summary> **Before** ``` config.compute Which accelerators to run on and how many. Supported accelerator types: GPU_1xH100 - 1 accelerator per node GPU_8xH100 - 8 accelerators per node GPU_1xRTX6000 - 1 accelerator per node Fields: num_accelerators Total number of GPUs to allocate. accelerator_type Which accelerator to run on, e.g. GPU_1xA10. pool_id GPU pool to run on, by id. priority_class Scheduling priority within the pool: BEST_EFFORT (lowest, preemptable) or NORMAL. Use "-h config.compute.<field>" for details on a field. ``` **After** ``` config.compute Which accelerators to run on and how many. Supported accelerator types: GPU_1xH100 - 1 accelerator per node GPU_8xH100 - 8 accelerators per node GPU_1xRTX6000 - 1 accelerator per node Fields: num_accelerators (required) Total number of GPUs to allocate. accelerator_type (required) Which accelerator to run on, e.g. GPU_1xA10. Provisioned capacity (optional): pool_id GPU pool to run on, by id. priority_class Scheduling priority within the pool: BEST_EFFORT (lowest, preemptable) or NORMAL. For details on a field, run "databricks air run -h config.compute.<field>". ``` </details> <details><summary><code>databricks air run -h config.environment.version</code></summary> **Before** ``` config.environment.version Client image version to pin (default: 6). See environment version release notes: https://docs.databricks.com/aws/en/release-notes/serverless/environment-version/ Type: string or int Required: no ``` **After** ``` config.environment.version Managed environment to start from, e.g. 6 for the Standard environment or databricks_ai_v6 for the Databricks AI environment (default: 6). Standard includes CUDA but, from version 5, not PyTorch; add it with dependencies. The Databricks AI environment adds PyTorch, Transformers, and other ML libraries. See Docs below for supported versions and package lists. Docs: AWS: https://docs.databricks.com/aws/en/machine-learning/ai-runtime/develop-workloads/environment Azure: https://learn.microsoft.com/azure/databricks/machine-learning/ai-runtime/develop-workloads/environment Type: string or int Required: no ``` </details> ## Why New users read `pools` and `pool_id` as prerequisites because they sit next to `run` and `accelerator_type`. The top-level help also listed commands A→Z, so `run` came last, and the YAML field list was one flat list. ## Tests - New unit tests for command grouping, the footer appearing only on `air -h`, config field headings and order, required-first ordering, the inline required markers, and the per-cloud Docs section (plus a check that no field help inlines a docs link). - Regenerated `acceptance/air/help`, `acceptance/air/config-help`, and `acceptance/help` outputs. - `./task fmt`, `./task checks`, `./task lint` pass. - Checked `environment.version` values with real runs: `4`, `5`, `6`, `databricks_ai_v5`, and `databricks_ai_v6` run; `1`-`3` fail at runtime ("client image version must be between 4 and 6"), and `7` and `databricks_ai_v7` are rejected at submit. - Checked the Required markers against a real workspace: omitting each required field fails `--dry-run` with the matching error, a run with only `experiment_name`, `compute`, and `command` succeeds, and both YAML examples shown in the help run successfully. This pull request and its description were written by Isaac. --------- Co-authored-by: Isaac <no-reply@databricks.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Changes
Remove the stale Public Preview label from the AIR entry in the general Databricks CLI help.
Why
AIR is GA, and the label had already been removed from the AIR command help.
Tests
Not run for PR submission. This is a minimal help-text-only change with an updated acceptance fixture.
This PR was written by Codex.