Developer Setup & Workflows
Relevant source files
The following files were used as context for generating this wiki page:
Meltano is a declarative, code-first data integration engine built on Python 3.10+. The project architecture is organized around specialized service classes, such as the VirtualEnvService and ProjectDirsService, to manage plugin environments and directory structures respectively.
Sources: README.md:46-49, AGENTS.md:7-14, AGENTS.md:60-63
Initial Development Environment Setup
Meltano uses uv as its primary package manager and nox as its task runner. Developers must have Python 3.10 or higher installed to begin contributing.
Dependency Management
Dependencies are managed using uv. To synchronize the local environment with the project's requirements, including all extras and development groups, use:
uv sync --all-extras --all-groups
Sources: AGENTS.md:11-20
Automated Task Runner
nox is utilized to automate development tasks, managing virtual environments and dependencies automatically. Default sessions typically include type checking, linting, and testing.
| Command | Description |
|---|---|
nox -l | List all available sessions |
nox | Run default sessions (mypy, pre-commit, pytest) |
nox -s pre-commit | Run only pre-commit checks |
Sources: AGENTS.md:38-47
Development Workflows
The project adheres to strict coding conventions, including required type hints and the use of MeltanoError for user-actionable error messages.
Quality Control Flow
The following flowchart represents the standard verification workflow before submitting code:
Sources: AGENTS.md:28-36, AGENTS.md:41-45
Testing Strategies
Testing is performed via pytest. The repository supports multiple database backends, which can be specified via environment variables.
- Specific Test:
uv run python -m pytest tests/path/to/test.py::test_function - Full Suite:
nox -t testornox -s pytest - Backend Specific:
PYTEST_BACKEND=postgresql nox -s pytest - Version Specific:
nox -p 3.14 -s pytest -- tests/path/to/subset
Sources: AGENTS.md:23-31
Project Configuration & Schema
Development is guided by a central JSON schema for meltano.yml. This schema defines how Meltano interacts with Python versions and virtual environment backends.
Virtual Environment Configuration
Meltano supports two primary backends for plugin virtual environments: virtualenv and uv. Recent updates have centralized this management into a VirtualEnvService that delegates to specific backend implementations.
Core Settings
Key project settings are defined in the schema to ensure consistent behavior across development environments:
| Setting | Type | Description |
|---|---|---|
requires_meltano | string | Version specifier for Meltano requirements |
venv.backend | enum | Options: virtualenv (default), uv |
python | string | Path or version of Python to use for plugins |
auto_install | boolean | Automatically install plugins on command invocation |
Sources: src/meltano/schemas/meltano.schema.json:44-51, src/meltano/schemas/meltano.schema.json:115-130, src/meltano/schemas/meltano.schema.json:281-285
Containerized Workflows
For developers who prefer Docker-based environments or need to test production-like setups, Meltano provides two types of images on Docker Hub.
- Slim Images:
meltano/meltano:latest-slim. Optimized for size and includes cloud storage support. - Full Images:
meltano/meltano:latest. Includes all database connectors and build tools.
# Verify version using the slim image
docker run --rm meltano/meltano:latest-slim --version
Sources: README.md:118-132
Documentation Workflow
Documentation is located in the docs/ directory. The build process is managed via Node.js commands defined in netlify.toml.
# Standard documentation build flow
npm install && npm run download-api-snippets && npm run build
Sources: netlify.toml:1-11
Meltano encourages the use of AI coding agents for development, provided developers follow the specific instructions in the Agentic Coding guide and maintain high quality and disclosure standards.
Sources: CONTRIBUTING.md:16-20, AGENTS.md:1-5