datahub AGENTS.md

DataHub — Agent Development Guide

This is the canonical reference for working with the DataHub codebase. It applies to all coding agents (Claude Code, Cursor, Codex CLI, Devin, etc.) and human developers alike.

Code Navigation (LSP)

Prefer LSP tools over Grep for code navigation tasks:

• Use goToDefinition to find where something is defined
• Use findReferences to find all call sites
• Use workspaceSymbol to find symbols by name
• Use diagnostics after any edit to catch type errors immediately

See docs/lsp-setup.md for installation and configuration.

Essential Commands

Build and test:

./gradlew build           # Build entire project
./gradlew check           # Run all tests (Python/JS lint lives in lint-jobs.yml / :module:lint)
./gradlew lintCheck       # Run all lint checks (Python, JS, GraphQL, markdown, Java)
./gradlew lintFix         # Auto-fix all lint issues
./gradlew format          # Format all code (Java, Markdown, GraphQL, YAML)

# Note that each directory typically has a build.gradle file, but the available tasks follow similar conventions.

# Java code.
./gradlew spotlessApply   # Java code formatting

# Python code.
./gradlew :metadata-ingestion:testQuick     # Fast Python unit tests
./gradlew :metadata-ingestion:lint          # Python linting (ruff, mypy)
./gradlew :metadata-ingestion:lintFix       # Python linting auto-fix (ruff only)

# Markdown, GraphQL, YAML formatting
./gradlew :datahub-web-react:mdPrettierWrite        # Format markdown files
./gradlew :datahub-web-react:graphqlPrettierWrite   # Format GraphQL schemas
./gradlew :datahub-web-react:githubActionsPrettierWrite # Format GitHub Actions

IMPORTANT: Verifying Python code changes:

• ALWAYS use ./gradlew :metadata-ingestion:lintFix to verify Python code changes
• NEVER use python3 -m py_compile - it doesn't catch style issues or type errors
• NEVER use ruff or mypy commands directly - use the Gradle task instead
• lintFix runs ruff formatting and fixing automatically, ensuring code quality
• For smoke-test changes, the lintFix command will also check those files