Skip to content

AGENTS.md

Latest commit

 

History

History
107 lines (83 loc) · 4.86 KB

AGENTS.md

File metadata and controls

107 lines (83 loc) · 4.86 KB

Databricks SDK for Go

Go SDK for the Databricks platform. Auto-generated API clients from OpenAPI specs, with hand-written authentication, configuration, and transport infrastructure.

For scoped coding rules, skills, and prompt templates, see the .agent/ directory.

Rules (.agent/rules/)

  • api-design.md — API design principles for the Databricks SDK.
  • error-handling.md — Error handling conventions for the Databricks SDK.
  • style-guide.md — Go code style and naming conventions for the Databricks SDK.
  • testing.md — Testing standards and anti-patterns for the Databricks SDK.

Skills (.agent/skills/)

  • write-pr-description — Write or improve a GitHub pull request description.

Prompts (.agent/prompts/)

  • code-review.md — Review PR or code changes for backward compatibility, correctness, and style.

Development

Prerequisites: Go 1.24+ (see go.mod), goimports, staticcheck, gotestsum.

make build      # go build ./...
make test       # Unit tests with coverage
make fmt        # goimports + gofmt
make lint       # staticcheck ./...
make integration # Integration tests (requires cloud env)
make vendor     # Vendor dependencies
make coverage   # View HTML coverage report
make codegen    # Regenerate service/ from OpenAPI specs

CI runs make test across Go 1.24, 1.25, and 1.26; lint and fmt run on Go 1.26. Code must compile on all CI versions — do not use stdlib APIs newer than Go 1.24 (the module's minimum version in go.mod) without a local shim.

Architecture

├── apierr/         # API error types and handling
├── client/         # High-level DatabricksClient (wraps workspace + account APIs)
├── config/         # Authentication and client configuration (core, hand-written)
├── credentials/    # Credential providers (OAuth, PAT, Azure, GCP, etc.)
├── experimental/   # Experimental features and generated mocks
├── httpclient/     # HTTP transport layer, request/response handling
├── internal/       # Internal utilities
├── listing/        # Iterator patterns for paginated API responses
├── logger/         # Logging infrastructure
├── marshal/        # JSON marshalling utilities
├── openapi/        # Code generator (reads OpenAPI specs, generates service/)
├── retries/        # Retry logic and policies
├── service/        # Auto-generated API service clients (DO NOT EDIT)
├── useragent/      # User-agent string construction
├── .codegen/       # Code generation templates (.tmpl files)
└── qa/             # Integration test helpers (RandomName, RandomEmail, etc.)

Generated Code — DO NOT EDIT

  • service/ — API service clients, generated from OpenAPI specs. Every file starts with // Code generated from OpenAPI specs by Databricks SDK Generator. DO NOT EDIT.
  • experimental/mocks/ — Mock implementations, generated by mockery. Every file starts with // Code generated by mockery. DO NOT EDIT.

To regenerate: make codegen (requires OpenAPI specs). After regenerating, run make fmt and make lint.

Hand-written code lives in: config/, credentials/, httpclient/, apierr/, listing/, retries/, marshal/, logger/, useragent/, client/, internal/, openapi/.

Common Mistakes

  • Do NOT edit files in service/ or experimental/mocks/ — they are auto-generated and will be overwritten
  • Do NOT use context.Background() in production code (only in tests)
  • Do NOT add new files to service/ manually — update OpenAPI specs and run make codegen
  • Do NOT add dependencies without checking license compatibility (Apache 2.0 required)
  • Do NOT break backwards compatibility of exported APIs without discussion
  • Do NOT use os.Exit() outside of main.go entry points

Where to Put New Code

  1. New API service client? → Update OpenAPI spec, run make codegen
  2. New auth method? → credentials/ (implement CredentialsProvider interface)
  3. Auth config change? → config/
  4. HTTP transport change? → httpclient/
  5. New error type? → apierr/
  6. New pagination pattern? → listing/
  7. Retry logic change? → retries/
  8. Code generation change? → openapi/ and .codegen/ templates
  9. Experimental/unstable API? → experimental/ or config/experimental/

Pull Requests

PR template requires: Changes (linked issues + functionality) and Tests sections. All PRs must have the DCO sign-off (git commit -s). Run make fmt test lint before submitting.

Changelog

Every PR must update NEXT_CHANGELOG.md under the appropriate section (Breaking Changes, New Features and Improvements, Bug Fixes, Documentation, Internal Changes, or API Changes). CI will fail if the file is not modified.

For PRs that don't need a changelog entry (e.g., documentation-only, CI config, agentic coding infrastructure), add NO_CHANGELOG=true to the PR description body.