Contributing Guide
Relevant source files
The following files were used as context for generating this wiki page:
dbt-common is a shared library containing common utilities used by dbt-core and various dbt adapter implementations. This guide provides technical instructions for developers to set up their environments, run tests, manage dependencies, and follow the project's standards for code quality and changelog management.
Sources: README.md:3, CONTRIBUTING.md:3
Getting Started
To contribute code changes, you must first ensure you have the necessary tools and access. External contributors must fork the repository, while dbt Labs members can push directly to branches after cloning. All contributors are required to sign the Contributor License Agreement before their Pull Requests can be merged.
Sources: CONTRIBUTING.md:25-45
Development Workflow
The following diagram illustrates the standard workflow for external contributors:
Sources: CONTRIBUTING.md:33-45
Environment Setup
The project uses hatch for project management and environment orchestration. Developers should use Python version 3.10 or higher.
Sources: pyproject.toml:6, CONTRIBUTING.md:65
Required Tooling
The following tools are utilized to maintain code quality:
- hatch: Project management and environment creation.
- flake8: Linting for PEP8 compliance.
- black: Deterministic code formatting.
- mypy: Static type checking.
- pre-commit: Git hooks to run checks automatically.
- changie: Automated changelog entry generation.
Sources: CONTRIBUTING.md:55-63
Dependency Management
Dependencies are defined in pyproject.toml under specific features (lint, test, build).
| Feature | Description | Key Packages |
|---|---|---|
| lint | Tools for static analysis and formatting | black, flake8, mypy, pytest |
| test | Tools for running automated tests | pytest, pytest-mock, hypothesis |
| build | Tools for packaging and distribution | wheel, twine |
Sources: pyproject.toml:39-66
Testing and Code Quality
Development actions are managed through hatch commands, which automatically handle environment creation based on the configurations in pyproject.toml.
Common Hatch Commands
| Category | Command | Description |
|---|---|---|
| Testing | hatch run test:unit | Executes all unit tests using pytest |
| Linting | hatch run lint:all | Runs black, flake8, and mypy checks |
| Environment | hatch shell | Enters a shell with all project and dev requirements |
| Utilities | hatch run proto | Regenerates protobuf definitions for events |
Sources: CONTRIBUTING.md:88-100, pyproject.toml:84-110
Protobuf Management
The project relies on protobuf for event definitions. When modifying events, developers must update the central repository and regenerate Python classes.
Documenting Changes
dbt-common uses changie to manage the CHANGELOG.md file. Manual edits to CHANGELOG.md are forbidden as they are overwritten during the build process.
Adding a Changelog Entry
- Install
changieon your local system. - Run
changie new. - Follow the interactive prompts to categorize your change (e.g., Features, Fixes, Under the Hood).
- Commit the resulting YAML file in the
.changes/unreleased/directory.
Sources: CONTRIBUTING.md:106-117, CHANGELOG.md:6-8
Standards and Conventions
Exception Handling
Contributors should use the established hierarchy in dbt_common/exceptions/base.py. All error messages must be scrubbed of secrets using the scrub_secrets utility before being displayed.
Sources: dbt_common/exceptions/base.py:22-192
Event Development
When adding new events to dbt_common/events/types.py, developers must ensure:
- A unique
codeis assigned based on the category (e.g., 'D' for Deprecations, 'Z' for Misc). - The event class inherits from the appropriate level mixin (
DebugLevel,InfoLevel,WarnLevel,ErrorLevel). - A descriptive
message()method is implemented.
Sources: dbt_common/events/types.py:15-27, dbt_common/events/README.md:21-27
Summary
Contributing to dbt-common requires strict adherence to automated testing and linting standards managed via hatch. By utilizing changie for version history and maintaining a structured exception and event hierarchy, contributors ensure the stability of the shared utilities used across the dbt ecosystem.
Sources: CONTRIBUTING.md:121-133, README.md:1-5