Contributing Guide & Code Quality

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• CLAUDE.md
• release/README.md
• release/prepare.py
• release/push.py
• pyproject.toml

Pydantic Logfire provides a structured environment for contributing to its OpenTelemetry-based observability platform. This guide outlines the development workflow, code quality enforcement through automated tooling, and the standardized release process managed by the maintainers.

The project emphasizes high-quality Python code, utilizing modern tools like uv for dependency management and ruff for linting. It follows a modular architecture where the core SDK implementation resides in logfire/, while a no-op shim for libraries is maintained in logfire-api/.
Sources: CLAUDE.md:1-2, CLAUDE.md:16-30, CONTRIBUTING.md:1-10

Development Environment Setup

To contribute to the Logfire SDK or documentation, developers must follow a specific sequence of setup steps to ensure environment parity with the CI system.

1. Fork and Clone: Initialize your local copy of the repository.
2. Dependency Management: Install uv as the primary package and project manager.
3. Hooks: Install pre-commit to automate quality checks before every commit.
4. Installation: Execute make install to provision dependencies.
5. Documentation: Use make docs to build or make docs-serve to view documentation locally.

Sources: CONTRIBUTING.md:3-11, CLAUDE.md:35-37

Core Makefile Commands

Command	Purpose
make install	Installs project dependencies using uv.
make test	Runs the full unit test suite via pytest.
make test-update-examples	Formats and updates code examples within the documentation.
make format	Runs code formatters (ruff).
make lint	Executes linters (ruff and pyright).
make typecheck	Explicitly runs pyright for static type analysis.
make generate-stubs	Updates .pyi stubs, essential for logfire-api consistency.

Sources: CONTRIBUTING.md:6-11, CLAUDE.md:8-10, release/README.md:33-33

Code Quality Standards

Code quality is enforced through a combination of linting, static analysis, and specific testing patterns.

Linting and Formatting

The project uses ruff for both linting and formatting, and pyright for strict type checking. These are configured to run automatically via pre-commit hooks. The configuration in pyproject.toml specifies a line length of 120 characters and uses single quotes for strings.
Sources: CLAUDE.md:8-10, pyproject.toml:161-171, pyproject.toml:208-214

Testing Patterns with Snapshots

Logfire utilizes inline_snapshot for testing spans. This allows developers to verify complex span structures by comparing them against automatically generated dictionaries.

from inline_snapshot import snapshot
from logfire.testing import TestExporter
import logfire

def test_example(exporter: TestExporter):
    with logfire.span("a span"):
        pass

    # Use 'uv run pytest --inline-snapshot=fix' to populate snapshot()
    assert exporter.exported_spans_as_dict(parse_json_attributes=True) == snapshot()

Sources: CLAUDE.md:39-50

For non-deterministic fields like timestamps or IDs, the project uses dirty_equals matchers (e.g., IsStr()) within the snapshots to maintain test reliability. Async tests are marked with @pytest.mark.anyio.
Sources: CLAUDE.md:52-60

Release Architecture & Process

The release process is divided into a semi-automated workflow for main releases and a manual process for branch-specific releases. This ensures consistency across the logfire and logfire-api packages.

Release Flow Logic

The following diagram illustrates the semi-automated release pipeline:

A visual representation of the automated steps taken when a maintainer initiates a new version release.
Sources: release/README.md:12-28, release/prepare.py:73-86

Key Release Components

Component	Responsibility	Relevant Files
Version Bumping	Updates version string in both root and logfire-api pyproject.toml files.	release/prepare.py
Stub Generation	Ensures no-op shim package logfire-api matches public SDK API.	release/prepare.py, CLAUDE.md
Note Generation	Fetches and cleans release notes using GitHub API based on Git tags.	release/prepare.py
Drafting	Automatically creates GitHub release drafts with curated changelogs.	release/push.py

Sources: release/prepare.py:12-25, release/prepare.py:34-60, release/push.py:38-54, CLAUDE.md:65-72

logfire-api Synchronisation

The logfire-api package is a critical no-op shim for library authors. It provides minimal implementations in logfire-api/logfire_api/__init__.py. This file must be kept in sync with the main logfire package's public API. During a release, make generate-stubs is invoked to refresh the .pyi stubs.
Sources: CLAUDE.md:65-72, release/prepare.py:28-30

Summary

Contributing to Logfire requires adherence to strict quality controls, including mandatory type checking and snapshot-based testing. The release process is highly structured to maintain version parity between the core SDK and the logfire-api shim, ensuring a reliable ecosystem for both direct users and library developers.
Sources: CLAUDE.md:8-10, CLAUDE.md:65-72, release/README.md:5-10